1. 什么是Swagger

Swagger是一個規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)。解析代碼里的注解生成JSON文件，通過Swagger UI生成網(wǎng)頁版的接口文檔，可以在上面做簡單的接口調(diào)試 。

2. 集成Swagger-UI

2.1 引入依賴

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

2.2 添加配置類

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)//
                .apiInfo(getApiInfo())//
                .select()//
                .apis(RequestHandlerSelectors.basePackage("com.autumn.mall.invest"))// 這里指定需要生成swagger接口的包路徑
                .paths(PathSelectors.any())//
                .build();
    }

    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder().title("招商微服務(wù)").version("1.0.0").build();
    }
}

2.3 添加注解

• controller類上增加@Api注解。
• 方法上

@PostMapping
@ApiOperation(value = "新增或編輯實體", httpMethod = "POST")
@ApiImplicitParam(name = "entity", value = "實體類", required = true)
public ResponseResult<String> save(@Valid @RequestBody T entity) {
    return new ResponseResult(CommonsResultCode.SUCCESS, getCrudService().save(entity));
}

這樣三步就可以讓Swagger幫我們生成save方法的接口文檔了，啟動服務(wù)，通過瀏覽器訪問http://ip:port/swagger-ui.html就可以看到生成好的接口文檔：

3. Swagger注解

常用到的注解有：

• Api
• ApiModel
• ApiModelProperty
• ApiOperation
• ApiImplicitParam

3.1 Api

Api 用在類上，通常用來說明該類的作用?？梢詷?biāo)記一個Controller類做為swagger文檔資源，使用方式：

@Api(value = "樓層管理")
public class FloorController extends AbstractSupportStateController<Floor, UsingState> implements FloorApi {}

• 常見屬性

3.2 ApiOperation

ApiOperation 用在方法上，說明方法的作用，每一個url資源的定義，使用方式：

@PostMapping
@ApiOperation(value = "新增或編輯實體", httpMethod = "POST")
@ApiImplicitParam(name = "entity", value = "實體類", required = true)
public ResponseResult<String> save(@Valid @RequestBody T entity) {
    return new ResponseResult(CommonsResultCode.SUCCESS, getCrudService().save(entity));
}

• 常見屬性

3.3 ApiImplicitParam

ApiImplicitParam 用在方法上，對方法的參數(shù)進(jìn)行描述。若方法有多個入?yún)?，則可以使用@ApiImplicitParams注解。

• 常見屬性

3.4 ApiModel

該注解用于描述一個model的信息，使用方式：

@Data
@Entity
@Table(name = "invest_store")
@ApiModel(description = "項目")
public class Store implements IsEntity {

    @Id
    @ApiModelProperty(value = "唯一標(biāo)識", dataType = "String")
    private String uuid;

    @NotBlank
    @Length(max = 32, message = "代碼最大長度不超過32")
    @ApiModelProperty(value = "代碼", dataType = "String")
    private String code;

    @NotBlank
    @Length(max = 64, message = "名稱最大長度不超過64")
    @ApiModelProperty(value = "名稱", dataType = "String")
    private String name;

    @Enumerated(value = EnumType.STRING)
    @ApiModelProperty(value = "狀態(tài)", dataType = "UsingState")
    private UsingState state;

    @Length(max = 1024, message = "說明最大長度不超過64")
    @ApiModelProperty(value = "說明", dataType = "String")
    private String remark;
}

• 常見屬性

3.5 ApiModelProperty

描述model中的屬性，常見屬性：