(轉發) swagger註釋API詳細說明
阿新 • • 發佈:2018-08-10
produce clas nbsp per restful val med ryu 當前 隨著互聯網技術的發展,現在的網站架構基本都由原來的後端渲染,變成了:前端渲染、前後端分離的形態,而且前端技術和後端技術在各自的道路上越走越遠。 前端和後端的唯一聯系,變成了API接口;API文檔變成了前後端開發人員聯系的紐帶,變得越來越重要,
參考: https://blog.csdn.net/xupeng874395012/article/details/68946676 https://blog.csdn.net/yilishuku/article/details/81197448
隨著互聯網技術的發展,現在的網站架構基本都由原來的後端渲染,變成了:前端渲染、前後端分離的形態,而且前端技術和後端技術在各自的道路上越走越遠。 前端和後端的唯一聯系,變成了API接口;API文檔變成了前後端開發人員聯系的紐帶,變得越來越重要,swagger
就是一款讓你更好的書寫API文檔的框架。 --引用 RyuGou的專欄
API詳細說明
註釋匯總
作用範圍 |
API | 使用位置 |
對象屬性 | @ApiModelProperty | 用在出入參數對象的字段上 |
協議集描述 | @Api | 用於controller類上 |
協議描述 | @ApiOperation | 用在controller的方法上 |
Response集 | @ApiResponses | 用在controller的方法上 |
Response | @ApiResponse | 用在 @ApiResponses裏邊 |
非對象參數集 | @ApiImplicitParams | 用在controller的方法上 |
非對象參數描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法裏邊 |
描述返回對象的意義 | 用在返回對象類上 | 用在返回對象類上 |
@RequestMapping此註解的推薦配置
value, method,produces
示例:
@ApiOperation("信息軟刪除") @ApiResponses({ @ApiResponse(code = CommonStatus.OK, message = "操作成功"), @ApiResponse(code = CommonStatus.EXCEPTION, message = "服務器內部異常"), @ApiResponse(code= CommonStatus.FORBIDDEN, message = "權限不足") }) @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "Long", name = "id", value = "信息id", required = true) }) @RequestMapping(value = "/remove.json", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE) public RestfulProtocol remove(Long id) {
}
@ApiModelProperty(value = "標題") private String title;
@ApiImplicitParam
屬性 | 取值 | 作用 |
paramType | 查詢參數類型 | |
path | 以地址的形式提交數據 | |
query | 直接跟參數完成自動映射賦值 | |
body | 以流的形式提交 僅支持POST | |
header | 參數在request headers 裏邊提交 | |
form | 以form表單的形式提交 僅支持POST | |
dataType | 參數的數據類型 只作為標誌說明,並沒有實際驗證 | |
Long | ||
String | ||
name | 接收參數名 | |
value | 接收參數的意義描述 | |
required | 參數是否必填 | |
true | 必填 | |
false | 非必填 | |
defaultValue | 默認值 |
paramType 示例詳解
path
@RequestMapping(value = "/findById1/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@PathVariable(name = "id") Long id
body
@ApiImplicitParams({ @ApiImplicitParam(paramType = "body", dataType = "MessageParam", name = "param", value = "信息參數", required = true) }) @RequestMapping(value = "/findById3", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE) @RequestBody MessageParam param 提交的參數是這個對象的一個json,然後會自動解析到對應的字段上去,也可以通過流的形式接收當前的請求數據,但是這個和上面的接收方式僅能使用一個(用@RequestBody之後流就會關閉了)
header
@ApiImplicitParams({ @ApiImplicitParam(paramType = "header", dataType = "Long", name = "id", value = "信息id", required = true) }) String idstr = request.getHeader("id"); if (StringUtils.isNumeric(idstr)) { id = Long.parseLong(idstr); }
Form
@ApiImplicitParams({ @ApiImplicitParam(paramType = "form", dataType = "Long", name = "id", value = "信息id", required = true) }) @RequestMapping(value = "/findById5", method = RequestMethod.POST, produces = MediaType.APPLICATION_J
(轉發) swagger註釋API詳細說明