一、簡介
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 插件的教程(分享)就是小編分享給大家的全部內容了，希望能給大家一個參考，也希望大家多多支持武林網。