關(guān)于Swagger注釋API的使用說明
API詳細說明
注釋匯總
作用范圍 | API | 使用位置 |
---|---|---|
對象屬性 | @ApiModelProperty | 用在出入?yún)?shù)對象的字段上 |
協(xié)議集描述 | @Api | 用于controller類上 |
協(xié)議描述 | @ApiOperation | 用在controller的方法上 |
Response集 | @ApiResponses | 用在controller的方法上 |
Response | @ApiResponse | 用在 @ApiResponses里邊 |
非對象參數(shù)集 | @ApiImplicitParams | 用在controller的方法上 |
非對象參數(shù)描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里邊 |
描述返回對象的意義 | @ApiModel | 用在返回對象類上 |
@RequestMapping此注解的推薦配置
value
method
produces
示例
@ApiOperation("信息軟刪除") @ApiResponses({ @ApiResponse(code = CommonStatus.OK, message = "操作成功"), @ApiResponse(code = CommonStatus.EXCEPTION, message = "服務(wù)器內(nèi)部異常"), @ApiResponse(code = CommonStatus.FORBIDDEN, message = "權(quán)限不足") }) @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 | 查詢參數(shù)類型 | |
path | 以地址的形式提交數(shù)據(jù) | |
query | 直接跟參數(shù)完成自動映射賦值 | |
body | 以流的形式提交 僅支持POST | |
header | 參數(shù)在request headers 里邊提交 | |
form | 以form表單的形式提交 僅支持POST | |
dataType | 參數(shù)的數(shù)據(jù)類型 只作為標志說明,并沒有實際驗證 | |
Long | ||
String | ||
name | 接收參數(shù)名 | |
value | 接收參數(shù)的意義描述 | |
required | 參數(shù)是否必填 | |
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 = "信息參數(shù)", required = true) }) @RequestMapping(value = "/findById3", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE) @RequestBody MessageParam param
提交的參數(shù)是這個對象的一個json,然后會自動解析到對應(yīng)的字段上去,也可以通過流的形式接收當前的請求數(shù)據(jù),但是這個和上面的接收方式僅能使用一個(用@RequestBody之后流就會關(guān)閉了)
接收對象傳參的例子
在POJO上增加
package com.zhongying.api.model.base; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; @ApiModel(value="對象模型") public class DemoDoctor{ @ApiModelProperty(value="id" ,required=true) private Integer id; @ApiModelProperty(value="姓名" ,required=true) private String name; public Integer getId() { return id; } public void setId(Integer id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } @Override public String toString() { return "DemoDoctor [id=" + id + ", name=" + name + "]"; } }
注意: 在后臺采用對象接收參數(shù)時,Swagger自帶的工具采用的是JSON傳參, 測試時需要在參數(shù)上加入@RequestBody,正常運行采用form或URL提交時候請刪除。
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_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
以上為個人經(jīng)驗,希望能給大家一個參考,也希望大家多多支持腳本之家。
相關(guān)文章
Spring中實現(xiàn)定時調(diào)度的幾種方法
本篇文章主要介紹了Spring中實現(xiàn)定時調(diào)度示例,可以在無人值守的時候系統(tǒng)可以在某一時刻執(zhí)行某些特定的功能,有興趣的可以了解一下。2017-02-02淺析java修飾符訪問權(quán)限(動力節(jié)點Java學(xué)院整理)
Java有四種訪問權(quán)限,其中三種有訪問權(quán)限修飾符,分別為private,public和protected,還有一種不帶任何修飾符,下面通過本文給大家簡單介紹下java修飾符訪問權(quán)限相關(guān)知識,感興趣的朋友一起學(xué)習(xí)吧2017-04-04Java如何讀寫Properties配置文件(Properties類)
這篇文章主要介紹了Java如何讀寫Properties配置文件(Properties類),具有很好的參考價值,希望對大家有所幫助。如有錯誤或未考慮完全的地方,望不吝賜教2023-05-05詳解微信開發(fā)之Author網(wǎng)頁授權(quán)
微信開發(fā)中,經(jīng)常有這樣的需求:獲得用戶頭像、綁定微信號給用戶發(fā)信息,那么實現(xiàn)這些的前提就是授權(quán)!本文對此進行系統(tǒng)介紹,需要的朋友一起來看下吧2016-12-12解決SpringBoot ClassPathResource的大坑(FileNotFoundException)
這篇文章主要介紹了解決SpringBoot ClassPathResource的大坑(FileNotFoundException),具有很好的參考價值,希望對大家有所幫助。如有錯誤或未考慮完全的地方,望不吝賜教2021-06-06spring boot空屬性賦值問題與aspect日志實現(xiàn)方法
這篇文章主要介紹了spring boot空屬性賦值問題與aspect日志實現(xiàn)方法,本文給大家介紹的非常詳細,對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值,需要的朋友可以參考下2020-08-08