【开发指南】Swagger2自动生成接口文档

说明

前后端分离开发模式中，API文档是最好的沟通方式。

Swagger是一个规范和完整的框架。用于生成、描述、调用和可视化RESTful风格的Web服务。

特性

• 及时性：接口变更后，能够及时准确地通知相关前后端开发人员。
• 规范性：并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息。
• 一致性：接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧。
• 可测性：直接在接口文档上进行测试，以方便理解业务。

基本配置

1. common服务中配置依赖

   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.7.0</version>
   </dependency>
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.7.0</version>
   </dependency>
   

2. 创建config包

3. 创建配置类

   @Configuration
   @EnableSwagger2
   public class Swagger2Config {
   
       // web组Api
       @Bean
       public Docket webApiConfig() {
           return new Docket(DocumentationType.SWAGGER_2)
                   // 组名,只有一个组时可以不写
                   .groupName("webApi")
                   .apiInfo(webApiInfo())
                   .select()
                   // 设置过滤分组条件
                   // 排除有admin路径的和文件名为error的Api
                   .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                   .paths(Predicates.not(PathSelectors.regex("/error.*")))
                   .build();
       }
   
       // 生成web组Api的辅助方法
       public ApiInfo webApiInfo() {
           return new ApiInfoBuilder()
                   // 文档标题
                   .title("web api title")
                   // 文档描述
                   .description("web api description")
                   // 文档版本
                   .version("1.0")
                   // 文档作者：名字，网址，邮箱
                   .contact(new Contact("AydenBryan", "https://juejin.cn/user/246719932274269", "ayden_bryan@163.com"))
                   .build();
       }
   
       // admin组Api
       @Bean
       public Docket adminApiConfig() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .groupName("adminApi")
                   .apiInfo(adminApiInfo())
                   .select()
                   // 设置过滤分组条件
                   // 排除有web路径的和文件名为error的Api
                   .paths(Predicates.not(PathSelectors.regex("/web/.*")))
                   .paths(Predicates.not(PathSelectors.regex("/error.*")))
                   .build();
       }
   
       // 生成admin组Api的辅助方法
       public ApiInfo adminApiInfo() {
           return new ApiInfoBuilder()
                   // 文档标题
                   .title("admin api title")
                   // 文档描述
                   .description("admin api description")
                   // 文档版本
                   .version("1.0")
                   // 文档作者：名字，网址，邮箱
                   .contact(new Contact("AydenBryan", "https://juejin.cn/user/246719932274269", "ayden_bryan@163.com"))
                   .build();
       }
   }
   

4. 查看Swagger2文档

   http://服务ip:服务port/swagger-ui.html
   

   

API模型

如果想让接口文档测试接口返回的数据显示更多信息，可以配置API模型。

@Data
@ApiModel(value = "用户对象", description = "用户")
public class User {
    
    @ApiModelProperty("用户id")
    private String id;
    @ApiModelProperty("用户账号")
    private String username;
    @ApiModelProperty("用户密码")
    private String password;
    @ApiModelProperty(value = "用户创建时间", example = "2021-3-19 12:00:00")
    private Date createTime;
    @ApiModelProperty(value = "用户修改时间", example = "2021-3-19 12:00:00")
    private Date updateTime;
}

@ApiModel：用在返回对象类上，描述返回对象的意义。

@ApiModelProperty：用在出入参数对象的字段上，作用于对象属性。

接口和参数说明

如果想让接口文档中的接口和参数显示更多的信息，可以配置接口和参数说明。

@RestController
@Api(description = "用户接口")
public class UserController {

    @Autowired
    private UserService userService;

    @ApiOperation("根据id删除用户")
    public boolean removeUser(@ApiParam(name = "id", value = "用户id", required = true) String id) {
        return userService.removeUser(id);
    }
}

@Api：用于Controller类上，接口集描述。

@ApiOperation：用在Controller的方法上，接口描述。

@ApiParam：用在Controller的方法的参数上，接口参数描述。