MiniMall：整合Swagger-UI自動生成接口文檔

1. 什麼是Swagger

Swagger是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。解析代碼裏的註解生成JSON文件，通過Swagger UI生成網頁版的接口文檔，可以在上面做簡單的接口調試 。

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("招商微服務").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方法的接口文檔了，啓動服務，通過瀏覽器訪問http://ip:port/swagger-ui.html就可以看到生成好的接口文檔：

3. Swagger註解

常用到的註解有：

• Api
• ApiModel
• ApiModelProperty
• ApiOperation
• ApiImplicitParam

3.1 Api

Api 用在類上，通常用來說明該類的作用。可以標記一個Controller類做爲swagger文檔資源，使用方式：

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

• 常見屬性

屬性	說明
value	url的路徑值
tags	設置該值時，value值將被覆蓋
description	對api資源的描述
basePath	基礎路徑
hidden	配置爲true時將在文檔中隱藏

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));
}

• 常見屬性

屬性	說明
value	方法作用的描述
httpMethod	請求方法
description	對api資源的描述
hidden	配置爲true時將在文檔中隱藏
response	返回的對象

3.3 ApiImplicitParam

ApiImplicitParam 用在方法上，對方法的參數進行描述。若方法有多個入參，則可以使用@ApiImplicitParams註解。

• 常見屬性

屬性	說明
name	參數名
value	參數名稱
dataType	參數類型
required	是否必要
defaultValue	默認值

3.4 ApiModel

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

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

    @Id
    @ApiModelProperty(value = "唯一標識", 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 = "狀態", dataType = "UsingState")
    private UsingState state;

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

• 常見屬性

屬性	說明
value	model名稱
description	描述信息
parent	父類

3.5 ApiModelProperty

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

屬性	說明
value	字段描述
dataType	字段類型
required	是否必要

——End—— 更多精彩分享，可掃碼關注微信公衆號哦。