SpringBoot 集成 Swagger2

Swagger2

1. Swagger 简介

Swagger是非常流行的API管理工具，支持整个API的生命周期，包括API设计、开发及测试。

2. 集成 Swagger2

2.1 添加依赖

<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.2 编写Swagger2配置类

@Configuration
@EnableSwagger2
public class Swagger2 {
    // 控制开关
    @Value("${swagger.show}")
    private boolean swaggerShow;
    
    public Docket createUserApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.greedy.web.task"))
            .paths(PathSelectors.any())
            .build()
            .groupName("task")
            .enable(swaggerShow);
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("STARK API")
            .description("接口文档")
            .termsOfServiceUrl("/")
            .version("v1.0")
            .build();
    } 
}

方法说明

• apiInfo()：指定接口文档的基本说明信息，例如：文档标题、文档描述、服务的URL、文档版本、作者、联系邮箱等等
• groupName()：为API设置分组名称
• select()：返回一个ApiSelectorBuilder实例，用来控制哪些API接口可以暴露
• apis()：ApiSelectorBuilder的成员方法，用来指定需要暴露的API所属的包
• paths()：ApiSelectorBuilder的成员方法，用来过滤API路由路径
• build()：返回一个Docket实例
• enable()：文档显示的控制开关

3. Swagger相关注解

(1) @Api 注解
作用在类上，用来描述Controller的作用，同一个Controller下的API作为一个分组
常用属性：

• value：URL的路径值
• tags：API分组标签，用来说明Controller的作用，如果设置了tags，则value会被覆盖
• description：API分组说明

(2) @ApiOperation 注解
作用在方法上，用来描述API接口
常用属性：

• value：API接口说明

(3) @ApiImplicitParam 注解
作用在方法上，用来描述单个参数的信息
常用属性：

• name：参数名
• value：参数中文描述
• required：是否必传
• defaultValue：参数默认值
• dataType：参数类型

(4) @ApiImplicitParams 注解
作用在方法上，用来描述多个参数的信息，属性类型为@ApiImplicitParam注解的数组

(5) @ApiIgnore 注解
作用在类上、方法上、参数上，用来忽略API接口或者接口的参数

(6) @ApiModel 注解
作用在JavaBean上，表示用对象来接收参数
常用属性：

• value：为模型提供备用名称
• descripton：为模型提供详细描述

(7) @ApiProperty 注解
作用在JavaBean的属性上，用来描述对象的字段
常用属性：

• name：属性名称
• value：属性中文描述
• dataType：属性的数据类型