Swagger2

1. Swagger 簡介

Swagger是非常流行的API管理工具，支持整個API的生命周期，包括API設(shè)計、開發(fā)及測試。

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 {
    // 控制開關(guān)
    @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()：指定接口文檔的基本說明信息，例如：文檔標題、文檔描述、服務(wù)的URL、文檔版本、作者、聯(lián)系郵箱等等
• groupName()：為API設(shè)置分組名稱
• select()：返回一個ApiSelectorBuilder實例，用來控制哪些API接口可以暴露
• apis()：ApiSelectorBuilder的成員方法，用來指定需要暴露的API所屬的包
• paths()：ApiSelectorBuilder的成員方法，用來過濾API路由路徑
• build()：返回一個Docket實例
• enable()：文檔顯示的控制開關(guān)

3. Swagger相關(guān)注解

(1) @Api 注解
作用在類上，用來描述Controller的作用，同一個Controller下的API作為一個分組
常用屬性：

• value：URL的路徑值
• tags：API分組標簽，用來說明Controller的作用，如果設(shè)置了tags，則value會被覆蓋
• description：API分組說明

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

• value：API接口說明

(3) @ApiImplicitParam 注解
作用在方法上，用來描述單個參數(shù)的信息
常用屬性：

• name：參數(shù)名
• value：參數(shù)中文描述
• required：是否必傳
• defaultValue：參數(shù)默認值
• dataType：參數(shù)類型

(4) @ApiImplicitParams 注解
作用在方法上，用來描述多個參數(shù)的信息，屬性類型為@ApiImplicitParam注解的數(shù)組

(5) @ApiIgnore 注解
作用在類上、方法上、參數(shù)上，用來忽略API接口或者接口的參數(shù)

(6) @ApiModel 注解
作用在JavaBean上，表示用對象來接收參數(shù)
常用屬性：

• value：為模型提供備用名稱
• descripton：為模型提供詳細描述

(7) @ApiProperty 注解
作用在JavaBean的屬性上，用來描述對象的字段
常用屬性：

• name：屬性名稱
• value：屬性中文描述
• dataType：屬性的數(shù)據(jù)類型