簡介
官網
github
swagger-springmvc: https://github.com/martypitt/swagger-springmvc
swagger-ui: https://github.com/swagger-api/swagger-ui
swagger-core: https://github.com/swagger-api/swagger-core
swagger-spec：https://github.com/swagger-api/swagger-spec
swagger的作用
1.接口的文檔在線自動生成。
2.功能測試。
爲什麼要用swagger？
爲了減少與其他團隊平時開發期間的頻繁溝通成本，傳統做法我們會創建一份RESTful API文檔來記錄所有接口細節，然而這樣的做法有以下幾個問題：
- 由於接口衆多，並且細節複雜（需要考慮不同的HTTP請求類型、HTTP頭部信息、HTTP請求內容等），高質量地創建這份文檔本身就是件非常喫力的事，下游的抱怨聲不絕於耳。
- 隨着時間推移，不斷修改接口實現的時候都必須同步修改接口文檔，而文檔與代碼又處於兩個不同的媒介，除非有嚴格的管理機制，不然很容易導致不一致現象。
常用註解
| 註解 | 作用 | 示例 |
| @Api | 用在Controller類上 | @Api(value = "用戶管理類", description = "Operations about user") |
| @ApiOperation | 用在Controller方法上 | @ApiOperation( value = "Find purchase order by ID", notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions", response = Order, tags = {"Pet Store"}) |
| @ApiImplicitParam | 用在Controller方法上或者@ApiImplicitParams裏。給方法入參增加說明 | @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User") |
| @ApiImplicitParams | 用在Controller方法上。給方法入參增加說明 | @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long"), @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User") }) |
| @ApiParam | 可用在Controller方法、參數、屬性上。 |
public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true) User user) |
| @ApiResponse | 用在controller的方法上或者@ApiResponses裏 | @ApiResponse(code = 400, message = "Invalid user supplied") |
| @ApiResponses | 用在controller的方法上 | @ApiResponses({ @ApiResponse(code = CommonStatus.OK, message = "操作成功"), @ApiResponse(code = CommonStatus.EXCEPTION, message = "服務器內部異常"), @ApiResponse(code = CommonStatus.FORBIDDEN, message = "權限不足") }) |
| @ResponseHeader | 用在controller的方法上 |
@ResponseHeader(name="head1",description="response head conf") |
| @ApiModel | 用在返回對象類上 | @ApiModel |
| @ApiModelProperty | 用在返回對象類的屬性 |
@ApiModelProperty(notes = "錯誤消息") |
@ApiImplicitParam
|
屬性 |
取值 |
作用 |
|
paramType |
|
查詢參數類型 |
|
|
path |
以地址的形式提交數據 |
|
|
query |
直接跟參數完成自動映射賦值 |
|
|
body |
以流的形式提交 僅支持POST |
|
|
header |
參數在request headers 裏邊提交 |
|
|
form |
以form表單的形式提交。僅支持POST |
|
dataType |
|
參數的數據類型 只作爲標誌說明，並沒有實際驗證 |
|
|
Long |
|
|
|
String |
|
|
name |
|
接收參數名 |
|
value |
|
接收參數的意義描述 |
|
required |
|
參數是否必填 |
|
|
true |
必填 |
|
|
false |
非必填 |
|
defaultValue |
|
默認值 |
Content Type
其他網址
HTTP系列--Content type_feiying0canglang的博客-CSDN博客