快捷導(dǎo)航

關(guān)于Swagger注釋API的使用說明

更新時間：2022年06月14日 10:41:41 作者：嶼麟

這篇文章主要介紹了關(guān)于Swagger注釋API的使用說明，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教

API詳細(xì)說明

注釋匯總

作用范圍	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 = "標(biāo)題")
    private String  title;

@ApiImplicitParam

屬性	取值	作用
paramType		查詢參數(shù)類型
	path	以地址的形式提交數(shù)據(jù)
	query	直接跟參數(shù)完成自動映射賦值
	body	以流的形式提交僅支持POST
	header	參數(shù)在request headers 里邊提交
	form	以form表單的形式提交僅支持POST
dataType		參數(shù)的數(shù)據(jù)類型只作為標(biāo)志說明，并沒有實際驗證
	Long
	String
name		接收參數(shù)名
value		接收參數(shù)的意義描述
required		參數(shù)是否必填
	true	必填
	false	非必填
defaultValue		默認(rèn)值

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)的字段上去，也可以通過流的形式接收當(dā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)驗，希望能給大家一個參考，也希望大家多多支持腳本之家。

您可能感興趣的文章: