在spring-boot中使用Swagger
在spring-boot中使用Swagger
配置
1.需要依賴兩個包：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${springfox-version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId
<version>${springfox-version}</version>
</dependency>
第一個是API獲取的包，第二是官方給出的一個ui介面。這個介面可以自定義，預設是官方的，對於安全問題，以及ui路由設定需要著重思考。
2.swagger的configuration
需要特別注意的是swagger scan base package,這是掃描註解的配置，即你的API介面位置。
當然，scan package 也可以換成別的條件，比如：
3.在API上做一些宣告
4.設定訪問API doc的路由
在配置檔案中，application.yml中宣告：
springfox.documentation.swagger.v2.path: /api-docs
這個path就是json的訪問request mapping.可以自定義，防止與自身程式碼衝突。
API doc的顯示路由是：http://localhost:8080/swagger-ui.html
如果專案是一個webservice，通常設定home / 指向這裡：
5.新建實體類User，基本欄位如下
- 簡單型別
- 複雜型別
- 實體類eclipse模板
- 實體類Idea模板
6.全部註釋列表
@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中配置 |
7.文件編寫規範建議
- 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：伺服器返回狀態碼的簡短說明
sample：header中傳遞token
@ApiImplicitParams({@ApiImplicitParam(name = "TOKEN", value = "Authorization token", required = true, dataType = "string", paramType = "header")})