秒懂API文件工具swagger的使用
swagger是一個介面文件的生成框架
為什麼要使用swagger?
區別去傳統文件的兩個優點:1.生成線上文件動態更新 (文件根據當前的介面生成) 避免了文件版本多,程式碼文件不同步等問題
2.線上restful形式的介面 邊看文件的同時測試介面,取代了了傳統的postman、curl等,那是相當的方便
如何使用? 這裡用spring boot的restful開發做講解,IDE使用intelli idea
第一步 新增maven依賴
在你的api專案的pom.xml 中新增兩個依賴
springfox-swagger2 和springfox-swagger-ui 下載到maven的中央倉庫 http://mvnrepository.com/
第二步 建立swagger2配置類
如上程式碼所示,通過@Configuration
註解,讓Spring來載入該類配置。再通過@EnableSwagger2
註解來啟用Swagger2。
再通過createRestApi
函式建立Docket
的Bean之後,apiInfo()
用來建立該Api的基本資訊(這些基本資訊會展現在文件頁面中)。select()
函式返回一個ApiSelectorBuilder
例項用來控制哪些介面暴露給Swagger來展現,本例採用指定掃描的包路徑來定義,Swagger會掃描該包下所有Controller定義的API,併產生文件內容(除了被@ApiIgnore
指定的請求)。
第三步 開啟swagger2 啟動類加註解@Enableswagger2
第四步 給函式添加註解
在完成了上述配置後,其實已經可以生產文件內容,但是這樣的文件主要針對請求本身,而描述主要來源於函式等命名產生,對使用者並不友好,我們通常需要自己增加一些說明來豐富文件內容。如下所示,我們通過@ApiOperation
註解來給API增加說明、通過@ApiImplicitParams
、@ApiImplicitParam
註解來給引數增加說明。
這樣swagger2與springboot就整合完畢了。
看下最終效果吧:
輸入id後,我們可以看到查詢結果:、
是不是很方便,我們不用像postman一樣來編寫入口,swagger2自動完成:
而且實時更新:
全部註釋列表
@Api
Api 標記可以標記一個Controller類做為swagger 文件資源,使用方式
屬性名稱 | 備註 |
---|---|
value | url的路徑值 |
tags | 如果設定這個值、value的值會被覆蓋 |
description | 對api資源的描述 |
basePath | 基本路徑可以不配置 |
position | 如果配置多個Api 想改變顯示的順序位置 |
produces | For example, “application/json, application/xml” |
consumes | For example, “application/json, application/xml” |
protocols | Possible values: http, https, ws, wss. |
authorizations | 高階特性認證時配置 |
hidden | 配置為true 將在文件中隱藏 |
@ApiOperation每一個url資源的定義,使用方式
屬性名稱 | 備註 |
---|---|
value | url的路徑值 |
tags | 如果設定這個值、value的值會被覆蓋 |
description | 對api資源的描述 |
basePath | 基本路徑可以不配置 |
position | 如果配置多個Api 想改變顯示的順序位置 |
produces | For example, “application/json, application/xml” |
consumes | For example, “application/json, application/xml” |
protocols | Possible values: http, https, ws, wss. |
authorizations | 高階特性認證時配置 |
hidden | 配置為true 將在文件中隱藏 |
response | 返回的物件 |
responseContainer | 這些物件是有效的 “List”, “Set” or “Map”.,其他無效 |
httpMethod | “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH” |
code | http的狀態碼 預設 200 |
extensions | 擴充套件屬性 |
@ApiParam標記
public ResponseEntity createUser(@RequestBody @ApiParam(value = “user”, required = true) User user)
屬性名稱 | 備註 |
---|---|
name | 屬性名稱 |
value | 屬性值 |
defaultValue | 預設屬性值 |
allowableValues | 可以不配置 |
required | 是否屬性必填 |
access | 不過多描述 |
allowMultiple | 預設為false |
hidden | 隱藏該屬性 |
example | 舉例子 |
@ApiImplicitParam對容器的描述
屬性名稱 | 備註 |
---|---|
name | 屬性名稱 |
value | 屬性值 |
defaultValue | 預設值 |
allowableValues | 可以不可配置 |
required | 是否屬性必填 |
access | 不可過多描述 |
allowMutiple | 預設為false |
dataType | 資料型別 |
paramType | 引數型別 |
@ApiResponse
屬性名稱 | 備註 |
---|---|
code | http的狀態碼 |
message | 描述 |
response | 預設響應類 Void |
reference | 參考ApiOperation中配置 |
responseHeaders | 參考 ResponseHeader 屬性配置說明 |
responseContainer | 參考ApiOperation中配置 |
@ResponseHeader(name=”head1”,description=”response head conf”)
屬性名稱 | 備註 |
---|---|
name | 響應頭名稱 |
description | 頭描述 |
response | 預設響應類 Void |
responseContainer | 參考ApiOperation中配置 |
4文件編寫規範建議
- entity的描述
@ApiModel(description = “我是描述”,value = “使用者”)
對實體的描述
description:在v2/api-docs的實體看到描述,
value的值在@ApiImplicitParam註解中的dataType可用,
@ApiModelProperty(value = “使用者姓名”,required = true,dataType = “String”)
private String name;
對欄位的描述
value:1,入參和出參的ModelModel Schema選項卡可見,2,在v2/api-docs的實體欄位描述可見
required:該屬性是否必填寫
dataType:該欄位的資料型別
- controller的描述
@Api(value = “API”, description = “使用者介面詳情”,tags=”A”)
對controler的描述
value:訪問某個controller的url的根路徑值
description:對於該controller的的大概描述
tags:把api介面進行分分組
@ApiOperation(value = “獲取使用者詳細資訊”, notes = “根據url的id來獲取使用者詳細資訊”,httpMethod =”GET”)
對該方法的描述
value:主頁面中對該介面的描述,位置在介面的最右邊
notes:點開介面後,第一段描述。
httpMethod:HTTP請求的動作名,可選值有:”GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”。
@ApiImplicitParam(name = “id”, value = “使用者ID”, required = true, dataType = “String”, paramType = “path”)
對引數的描述,如果多個引數需要用@ApiImplicitParams對其進行包裹
name:引數名稱
value:引數的簡短描述
required:是否必須傳遞的引數
dataType:引數型別,可以為類名,也可以為基本型別(String,int,Boolean)
paramType:引數的傳入(請求)型別,可選的值有path, query, body, header or form。(如果在路徑中提取引數用path比如:在/A/{XXX}路徑中得到XXX的值)
@ApiParam(name = “user”, value = “userValue”, required = true)
對引數元資訊的說明,一般這個註解只能被使用在JAX-RS 1.x/2.x的綜合環境下,和ApiImplicitParam註解類似
required:該引數是否必填
value:該引數的簡短介紹
@ApiResponse(code = 200, message = “Successful — 請求已完成”)
返回狀態碼的描述,如果有多個可以使用@ApiResponses註解進行包裹
code:伺服器返回的狀態碼
message:伺服器返回狀態碼的簡短說明
github地址:https://github.com/chinafire/swagger-example.git
swagger官方文件: https://swagger.io/docs/