swagger注释API详细说明

快来打我* 2022-06-18 08:22 193阅读 0赞

## API详细说明 ##

注释汇总

<table> 
 <thead> 
  <tr> 
   <th>作用范围</th> 
   <th align="center">API</th> 
   <th align="right">使用位置</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>对象属性</td> 
   <td align="center">@ApiModelProperty</td> 
   <td align="right">用在出入参数对象的字段上</td> 
  </tr> 
  <tr> 
   <td>协议集描述</td> 
   <td align="center">@Api</td> 
   <td align="right">用于controller类上</td> 
  </tr> 
  <tr> 
   <td>协议描述</td> 
   <td align="center">@ApiOperation</td> 
   <td align="right">用在controller的方法上</td> 
  </tr> 
  <tr> 
   <td>Response集</td> 
   <td align="center">@ApiResponses</td> 
   <td align="right">用在controller的方法上</td> 
  </tr> 
  <tr> 
   <td>Response</td> 
   <td align="center">@ApiResponse</td> 
   <td align="right">用在 @ApiResponses里边</td> 
  </tr> 
  <tr> 
   <td>非对象参数集</td> 
   <td align="center">@ApiImplicitParams</td> 
   <td align="right">用在controller的方法上</td> 
  </tr> 
  <tr> 
   <td>非对象参数描述</td> 
   <td align="center">@ApiImplicitParam</td> 
   <td align="right">用在@ApiImplicitParams的方法里边</td> 
  </tr> 
  <tr> 
   <td>描述返回对象的意义</td> 
   <td align="center">@ApiModel</td> 
   <td align="right">用在返回对象类上</td> 
  </tr> 
 </tbody> 
</table>

@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 #

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th align="center">取值</th> 
   <th align="right">作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>paramType</td> 
   <td align="center"></td> 
   <td align="right">查询参数类型</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td align="center">path</td> 
   <td align="right">以地址的形式提交数据</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td align="center">query</td> 
   <td align="right">直接跟参数完成自动映射赋值</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td align="center">body</td> 
   <td align="right">以流的形式提交 仅支持POST</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td align="center">header</td> 
   <td align="right">参数在request headers 里边提交</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td align="center">form</td> 
   <td align="right">以form表单的形式提交 仅支持POST</td> 
  </tr> 
  <tr> 
   <td>dataType</td> 
   <td align="center"></td> 
   <td align="right">参数的数据类型 只作为标志说明，并没有实际验证</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td align="center">Long</td> 
   <td align="right"></td> 
  </tr> 
  <tr> 
   <td></td> 
   <td align="center">String</td> 
   <td align="right"></td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td align="center"></td> 
   <td align="right">接收参数名</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td align="center"></td> 
   <td align="right">接收参数的意义描述</td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td align="center"></td> 
   <td align="right">参数是否必填</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td align="center">true</td> 
   <td align="right">必填</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td align="center">false</td> 
   <td align="right">非必填</td> 
  </tr> 
  <tr> 
   <td>defaultValue</td> 
   <td align="center"></td> 
   <td align="right">默认值</td> 
  </tr> 
 </tbody> 
</table>

# 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_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)