一、簡介
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函數的工作方式）。默認是服務器返回的順序不變。
四、Spring Boot 集成
依賴於 Spring Boot 中的 starter 和 autoconfig 組件。在 Boot 中使用 Swagger 是再輕松不過的事情了。
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
然后再配置上面提到的 SwaggerConfig.java（也能在 application.yml 中配置，個人更喜歡配置類的方式） 這樣就集成好了 swagger 組件和 swagger-ui 。怎么樣？簡單吧！