关于Swagger注释API的使用说明

2022-11-13 10:11:07 swagger 注释 使用说明

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)

以上为个人经验，希望能给大家一个参考，也希望大家多多支持。

相关文章