SpringMVC 中配置 Swagger 插件的教程(分享)

一、簡介

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#apimodel

@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函數的工作方式）。默認是服務器返回的順序不變。

以上這篇SpringMVC 中配置 Swagger 插件的教程(分享)就是小編分享給大家的全部內容了，希望能給大家一個參考，也希望大家多多支持億速云。