一、簡介
swagger的目標是為rest api定義一個與語言無關的標準接口，允許用戶發現和理解計算機服務的功能，而無需訪問源代碼。當通過swagger正確定義時，用戶可以用最少量的實現邏輯理解遠程服務并與之交互。類似于低級編程所做的接口。
二、實現步驟
1、添加 maven 依賴
|
1
2
3
4
5
|
<dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger2</artifactid> <version>2.6.1</version></dependency> |
2、swagger 配置類
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
|
@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 插件的教程(分享)就是小編分享給大家的全部內容了，希望能給大家一個參考，也希望大家多多支持服務器之家。
原文鏈接：http://www.cnblogs.com/jmcui/archive/2017/12/24/8098268.html
