關於Swagger註釋API的使用說明

Posted on by

API詳細說明

註釋匯總

作用范圍 API 使用位置
對象屬性 @ApiModelProperty 用在出入參數對象的字段上
協議集描述 @Api 用於controller類上
協議描述 @ApiOperation 用在controller的方法上
Response集 @ApiResponses 用在controller的方法上
Response @ApiResponse 用在 @ApiResponses裡邊
非對象參數集 @ApiImplicitParams 用在controller的方法上
非對象參數描述 @ApiImplicitParam 用在@ApiImplicitParams的方法裡邊
描述返回對象的意義 @ApiModel 用在返回對象類上

@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之後流就會關閉瞭）    

接收對象傳參的例子

在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 + "]";
    }    
}

註意： 在後臺采用對象接收參數時，Swagger自帶的工具采用的是JSON傳參， 測試時需要在參數上加入@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)

以上為個人經驗，希望能給大傢一個參考，也希望大傢多多支持WalkonNet。

推薦閱讀：