SpringMVC 中設定 Swagger 外掛

2020-06-16 16:58:16

一、簡介

Swagger的目標是為REST API定義一個與語言無關的標準介面，允許使用者發現和理解計算機服務的功能，而無需存取原始碼。當通過Swagger正確定義時，使用者可以用最少量的實現邏輯理解遠端服務並與之互動。類似於低階程式設計所做的介面。

二、實現步驟

1、新增 Maven 依賴

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

2、Swagger 設定類

@Configuration
@EnableSwagger2
//@ComponentScan(basePackageClasses = JgBjBaseInfoCompanyApi.class) 或者
@ComponentScan(basePackages = "com.summersoft.ts.schedule.supervision.controller") //要掃描的包路徑
public class SwaggerConfig {

    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select() //選擇哪些路徑和api會生成document
                .apis(RequestHandlerSelectors.any())//對所有Api進行監控
                .paths(PathSelectors.any()) //對所有路徑進行掃描
                .build();
    }

    /**
     * api具體資訊
     *
     * @return
     */
    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
                "對接服務平台API文件", //標題
                "", //描述
                "1.0", //版本
                "",
                "",
                "", //簽名
                "" //簽名連結
        );
        return apiInfo;
    }
}

3、Swagger 註解

Swagger 會去掃描SwaggerConfig 中設定的包路徑下的帶有Swagger 註解的類檔案，並最後生成一串掃描的Json檔案...

Swagger 註解說明：https://github.com/swagger-api/swagger-core/wiki/Annotations

@Api :用在類上，說明該類的作用,需要說明的是較老的版本用的value表示掃描生成的類名，1.5後要用tag 表示類名
@Api(tag= "UserController", description = "使用者相關api")
@ApiOperation :用在方法上，說明方法的作用
@ApiOperation(value = "查詢使用者", notes = "查詢使用者", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

@ApiParam ：用在參數列中，表明引數的含義

@ApiParam(value = "建立或更新距離當前時間(月)") Integer time

@ApiImplicitParams :用在方法上包含一組引數說明
@ApiImplicitParam :用在@ApiImplicitParams註解中，指定一個請求引數的各個方面
paramType：引數放在哪個地方
header–>請求引數的獲取：@RequestHeader
query–>請求引數的獲取：@RequestParam
path（用於restful介面）–>請求引數的獲取：@PathVariable
body（不常用）
form（不常用）
name：引數名
dataType：引數型別
required：引數是否必須傳
value：引數的意思
defaultValue：引數的預設值
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "唯一id", required = true, dataType = "Long", paramType = "path"),
})

@ApiResponses :用於表示一組響應
@ApiResponse :用在@ApiResponses中，一般用於表達一個錯誤的響應資訊
code：數位，例如400
message：資訊，例如”請求引數沒填好”
response：丟擲異常的類
@ApiResponses(value = {
@ApiResponse(code = 400, message = "No Name Provided")
})

@ApiModel :描述一個Model的資訊（這種一般用在post建立的時候，使用@RequestBody這樣的場景，請求引數無法使用@ApiImplicitParam註解進行描述的時候）
@ApiModel(value = "使用者實體類")
@ApiModelProperty :描述一個model的屬性
@ApiModelProperty(value = "登入使用者")

三、swagger-ui

有了上面的設定資訊，Swagger 就會幫我們掃描出所有的類資訊，並生成一個JSON檔案。想讓JSON檔案友好的展示在人們面前，需要用到 swagger-ui 這個元件：

1、 swagger-ui 使用說明：https://swagger.io/docs/swagger-tools/

2、下載 swagger-ui ,在webapp 目錄下新建一個swagger目錄，把 dist 目錄下的檔案，放入swagger目錄下，並修改index.html檔案，預設是從連線 http://petstore.swagger.io/v2/swagger.json 獲取 API 的 JSON，這裡需要將url值修改為 http://{ip}:{port}/{projectName}/api-docs的形式，{}中的值根據自身情況填寫。比如我的url值為：http://localhost:8080/vouchers/api-docs 。另外，需要設定一下Spring MVC的資源放行：<mvc:resources mapping="/swagger/**" location="/swagger/"/>

tips：預設的dist 目錄下沒有這麼多檔案，swagger-ui 可以自定義設定，這個是我們專案中使用的，不用改專案名，專案名動態獲取：https://files.cnblogs.com/files/jmcui/swagger.zip

3、swagger-ui 怎麼對展示的介面排序：

apisSorter ：對API /標籤列表應用排序。它可以是'alpha'（按名稱排序）或函數（請參閱Array.prototype.sort（）以了解sort函數的工作原理）。預設是伺服器返回的順序不變。

operationsSorter ：對每個API的操作列表應用一個排序。它可以是'alpha'（按字母數位排序），'method'（按HTTP方法排序）或函數（參見Array.prototype.sort（）來知道sort函數的工作方式）。預設是伺服器返回的順序不變。

本文永久更新連結地址：http://www.linuxidc.com/Linux/2017-12/149782.htm