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

一、簡(jiǎn)介

Swagger的目標(biāo)是為REST API定義一個(gè)與語(yǔ)言無(wú)關(guān)的標(biāo)準(zhǔn)接口，允許用戶發(fā)現(xiàn)和理解計(jì)算機(jī)服務(wù)的功能，而無(wú)需訪問(wèn)源代碼。當(dāng)通過(guò)Swagger正確定義時(shí)，用戶可以用最少量的實(shí)現(xiàn)邏輯理解遠(yuǎn)程服務(wù)并與之交互。類似于低級(jí)編程所做的接口。

二、實(shí)現(xiàn)步驟

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會(huì)生成document
  .apis(RequestHandlerSelectors.any())//對(duì)所有Api進(jìn)行監(jiān)控
  .paths(PathSelectors.any()) //對(duì)所有路徑進(jìn)行掃描
  .build();
 }

 /**
 * api具體信息
 *
 * @return
 */
 private ApiInfo apiInfo() {
 ApiInfo apiInfo = new ApiInfo(
  "對(duì)接服務(wù)平臺(tái)API文檔", //標(biāo)題
  "", //描述
  "1.0", //版本
  "",
  "",
  "", //簽名
  "" //簽名鏈接
 );
 return apiInfo;
 }
}

3、Swagger 注解

Swagger 會(huì)去掃描SwaggerConfig 中配置的包路徑下的帶有Swagger 注解的類文件，并最后生成一串掃描的Json文件...

Swagger 注解說(shuō)明：https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

@Api :用在類上，說(shuō)明該類的作用,需要說(shuō)明的是較老的版本用的value表示掃描生成的類名，1.5后要用tag 表示類名

@Api(tag= "UserController", description = "用戶相關(guān)api")

@ApiOperation :用在方法上，說(shuō)明方法的作用

@ApiOperation(value = "查找用戶", notes = "查找用戶", httpMethod = "GET", produces =

MediaType.APPLICATION_JSON_UTF8_VALUE)

@ApiParam ：用在參數(shù)列表中，表明參數(shù)的含義

@ApiParam(value = "創(chuàng)建或更新距離當(dāng)前時(shí)間(月)") Integer time

@ApiImplicitParams :用在方法上包含一組參數(shù)說(shuō)明

@ApiImplicitParam :用在@ApiImplicitParams注解中，指定一個(gè)請(qǐng)求參數(shù)的各個(gè)方面

paramType：參數(shù)放在哪個(gè)地方

header–>請(qǐng)求參數(shù)的獲取：@RequestHeader

query–>請(qǐng)求參數(shù)的獲?。篅RequestParam

path（用于restful接口）–>請(qǐng)求參數(shù)的獲?。篅PathVariable

body（不常用）

form（不常用）

name：參數(shù)名

dataType：參數(shù)類型

required：參數(shù)是否必須傳

value：參數(shù)的意思

defaultValue：參數(shù)的默認(rèn)值

@ApiImplicitParams({

@ApiImplicitParam(name = "id", value = "唯一id", required = true, dataType = "Long", paramType = "path"),
})

@ApiResponses :用于表示一組響應(yīng)

@ApiResponse :用在@ApiResponses中，一般用于表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息

code：數(shù)字，例如400

message：信息，例如”請(qǐng)求參數(shù)沒(méi)填好”

response：拋出異常的類

@ApiResponses(value = {
@ApiResponse(code = 400, message = "No Name Provided")
})

@ApiModel :描述一個(gè)Model的信息（這種一般用在post創(chuàng)建的時(shí)候，使用@RequestBody這樣的場(chǎng)景，請(qǐng)求參數(shù)無(wú)法使用@ApiImplicitParam注解進(jìn)行描述的時(shí)候）

@ApiModel(value = "用戶實(shí)體類")

@ApiModelProperty :描述一個(gè)model的屬性

@ApiModelProperty(value = "登錄用戶")

三、swagger-ui

有了上面的配置信息，Swagger 就會(huì)幫我們掃描出所有的 類信息，并生成一個(gè)JSON文件。想讓JSON文件友好的展示在人們面前，需要用到 swagger-ui 這個(gè)組件：

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

2、下載 swagger-ui ,在webapp 目錄下新建一個(gè)swagger目錄，把 dist 目錄下的文件，放入swagger目錄下，并修改index.html文件，默認(rèn)是從連接 http://petstore.swagger.io/v2/swagger.json 獲取 API 的 JSON，這里需要將url值修改為 http://{ip}:{port}/{projectName}/api-docs的形式，{}中的值根據(jù)自身情況填寫(xiě)。

比如我的url值為：

http://localhost:8080/vouchers/api-docs 。另外，需要配置一下Spring MVC的資源放行：<mvc:resources mapping="/swagger/**" location="/swagger/"/>

tips：默認(rèn)的dist 目錄下沒(méi)有這么多文件，swagger-ui 可以自定義配置，這個(gè)是我們項(xiàng)目中使用的，不用改項(xiàng)目名，項(xiàng)目名動(dòng)態(tài)獲取：https://files.cnblogs.com/files/jmcui/swagger.zip

3、swagger-ui 怎么對(duì)展示的接口排序：

apisSorter ：對(duì)API /標(biāo)簽列表應(yīng)用排序。它可以是'alpha'（按名稱排序）或函數(shù)（請(qǐng)參閱Array.prototype.sort（）以了解sort函數(shù)的工作原理）。默認(rèn)是服務(wù)器返回的順序不變。

operationsSorter ：對(duì)每個(gè)API的操作列表應(yīng)用一個(gè)排序。它可以是'alpha'（按字母數(shù)字排序），'method'（按HTTP方法排序）或函數(shù)（參見(jiàn)Array.prototype.sort（）來(lái)知道sort函數(shù)的工作方式）。默認(rèn)是服務(wù)器返回的順序不變。

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