本文共 7649 字，大约阅读时间需要 25 分钟。

  在日常的开发过程尤其是在前后端分离的开发中，后端往往需要给前端（Web、IOS、Android）或者第三方服务提供接口，这个时候后端就需要给前端提供一份详细的API说明文档。但是维护一份详细的文档并非易事。首先，编写一份详细的说明文档本身就是一件很费时费力的事情，另一方面，由于代码和文档是分离的，所以很容易导致文档和代码的不一致（比如代码中改了参数，文档中肯定也得跟着改，这不是搞事儿吗）。因此，本文将介绍SpringBoot如何整合Swagger2进行API文档维护，即通过Swagger来自动生成Restful API文档。

本文只是记录一下自己学习Swagger简单笔记，涉及的是其中的一些注解作用讲解，不会每一部分分开讲解。

导入相关依赖（lombok可根据自己习惯使用，作用就是通过注解方式省略getter、setter、toString等方法，导入依赖之后还需要idea下载插件）：

           
               
    
     org.projectlombok
                
    
     lombok
                
    
     true
            
           
           
           
               
    
     io.springfox
                
    
     springfox-swagger2
                
    
     2.9.2
    
                
                    
                         
      
       io.swagger
                          
      
       swagger-models
                      
                 
            
           
               
    
     io.swagger
                
    
     swagger-models
                
    
     1.5.22
            
           
           
               
    
     io.springfox
                
    
     springfox-swagger-ui
                
    
     2.9.2
            
   

Swagger相关注解：

上面注解并不是是一定要组合使用，比如说在Controller中不一定要先使用@Api才能使用@ApiOperation等注解。

package com.dl.swagger.config;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.core.env.Environment;import org.springframework.core.env.Profiles;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.ParameterBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.schema.ModelRef;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Contact;import springfox.documentation.service.Parameter;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;import java.util.ArrayList;import java.util.List;@Configuration    //加入到Spring容器中@EnableSwagger2  //开启swagger配置public class SwaggerConfig {
       @Autowired    private Environment environment;//形参方式其实也是注入进的    @Bean    public Docket createRestApi(){
     //Docket实例        Parameter token=new ParameterBuilder().name("token")                .description("用户登录令牌")                .parameterType("header")//query(请求体中)                .modelRef(new ModelRef("String"))                .build();        List
   
     parameters=new ArrayList<>(); //全局参数配置        parameters.add(token);        Profiles profiles=Profiles.of("dev","tools");  //多环境配置        boolean isEnable = environment.acceptsProfiles(profiles);//判断是否是该环境        return new Docket(DocumentationType.SWAGGER_2)//告诉Docket bean我们正在使用Swagger规范的版本2。                .groupName("用户组")//                .globalOperationParameters(parameters)  //全局配置，比如一些接口请求时候都需要token                .apiInfo(apiInfo())//                .ignoredParameterTypes(Integer.class, HttpSession.class) //接口忽略参数                .enable(isEnable)//是否开启swagger，可结合多环境进行配置                .select()                .apis(RequestHandlerSelectors.basePackage("com.dl.swagger.controller"))                .paths(PathSelectors.any())//接口配置过滤，any表示全部接口//                .paths(PathSelectors.ant("/user/**"))  //接口过滤                .build();    }    @Bean    public Docket helloDocket(){
     //分组        return new Docket(DocumentationType.SWAGGER_2)                .groupName("Hello组")                .apiInfo(apiInfo())                .select()                .build();    }    public ApiInfo apiInfo(){
    //创建ApiInfo对象，该对象提供有关API的一般信息，例如标题，版本，联系人或许可信息。        return new ApiInfoBuilder()                .title("个人Blog系统Restful API") //标题                .description("个人博客系统") //描述                .termsOfServiceUrl("http://localhost:8080/")                .contact(new Contact("童话ing","https://blog.csdn.net/dl962454?spm=1001.2014.3001.5113","swust_dl@163.com"))                .version("2.0") //版本                .build();    }}
   

Controller测试类：

package com.dl.swagger.controller;import com.dl.swagger.POJO.User;import com.dl.swagger.config.ClassAnnotation;import com.dl.swagger.config.FieldAnnotation;import io.swagger.annotations.*;import org.springframework.stereotype.Controller;import org.springframework.web.bind.annotation.*;import java.lang.annotation.Annotation;import java.lang.reflect.Field;@Api("用户相关controller")@Controller@RequestMapping("/user/")public class UserController {
       @ApiOperation("根据用户id获取用户信息")  //简单说明一下接口作用    @ApiImplicitParam(name="userId",value = "用户id",paramType = "int" ,dataType = "header",defaultValue = "2324",example = "12343") //接口参数列表    @ResponseBody    @GetMapping("getUser")    public User getUser(Integer userId){
           User user=new User(23345,"tonghua",true,25);        return user;    }    @ApiImplicitParam(name="token",value = "用户令牌")    @ResponseBody    @PostMapping("test")    public String Test(@RequestHeader("token") String token){
    //获取请求头中的参数        return "测试一下Swagger2";    }    @ApiOperation("新增用户")    @ApiImplicitParam(name="user",value = "用户信息")    @ResponseBody    @PutMapping("add")    public User addUser(@RequestBody User user){
    //实体类需要变成json才能被swagger扫描        return user;    }    @ApiOperation("根据用户名和密码登录")    @ApiImplicitParams({
     //多参数配置            @ApiImplicitParam(name="userName",value = "用户名"),            @ApiImplicitParam(name="password",value = "密码")    })    @ApiResponses({
    //返回响应组            @ApiResponse(code=200,message="成功",response=User.class),    })    @ResponseBody    @GetMapping("get")    public User selectUser(String userName,String password){
           User user=new User(123445,"TongHua",true,25);        return user;    }}

@ApiOperation，整个接口属性配置：

• value：接口说明，展示在接口列表。
• notes：接口详细说明，展示在接口的详情页。
• tags：接口的标签，相同标签的接口会在一个标签页下展示。
• httpMethod：支持的HTTP的方法。

@ApiImplicitParams，@ApiImplicitParam的容器，可包含多个@ApiImplicitParam注解

• name：参数名称
• value：参数说明
• required：是否必须
• dataType：数据类型

@ApiResponses，@ApiResponse容器，可以包含多个@ApiResponse注解

• code：返回结果的编码。
• message：返回结果的说明。
• response：返回结果对应的类。　
  　　　　　　　
  Model的User类：

package com.dl.swagger.POJO;import com.dl.swagger.config.ClassAnnotation;import com.dl.swagger.config.FieldAnnotation;import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;import lombok.AllArgsConstructor;import lombok.Data;import lombok.NoArgsConstructor;@Data  //getter、setter、toString@AllArgsConstructor@NoArgsConstructor@ApiModel(value = "用户实体类",description = "用户相关的bean配置，属性包含...")  //在实体类上边使用public class User {
       @ApiModelProperty("用户id")     private Integer userId;    @ApiModelProperty("用户名")    private String userName;    @ApiModelProperty("性别")    private boolean sex;    @ApiModelProperty("年龄")    private Integer age;}

@ApiModel是对整个类的属性的配置：

• value：类的说明
• escription：详细描述

@ApiModelProperty是对具体每个字段的属性配置：

• name：字段名称
• value：字段的说明
• required：是否必须
• example：示例值
• hidden：是否显示

简单示例图：

Swagger教程参见：

转载地址：https://dh-butterfly.blog.csdn.net/article/details/110148790 如侵犯您的版权，请留言回复原文章的地址，我们会给您删除此文章，给您带来不便请您谅解！