swagger常用注解说明

朴灿烈づ我的快乐病毒、 2022-04-10 07:39 283阅读 0赞

原文：[https://www.jianshu.com/p/12f4394462d5][https_www.jianshu.com_p_12f4394462d5]

常用到的注解有：

*  Api
 *  ApiModel
 *  ApiModelProperty
 *  ApiOperation
 *  ApiParam
 *  ApiResponse
 *  ApiResponses
 *  ResponseHeader

1. api标记

Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：

@Api(value = "/user", description = "Operations about user")

与Controller注解并列使用。 属性配置：

在SpringMvc中的配置如下：

@Controller
    @RequestMapping(value = "/api/pet", produces = {APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE})
    @Api(value = "/pet", description = "Operations about pets")
    public class PetController {
    
    }

2. ApiOperation标记

ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式：

@ApiOperation(
              value = "Find purchase order by ID",
              notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
              response = Order,
              tags = {"Pet Store"})

与Controller中的方法并列使用。  
属性配置：

<table> 
 <thead> 
  <tr> 
   <th>属性名称</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>url的路径值</td> 
  </tr> 
  <tr> 
   <td>tags</td> 
   <td>如果设置这个值、value的值会被覆盖</td> 
  </tr> 
  <tr> 
   <td>description</td> 
   <td>对api资源的描述</td> 
  </tr> 
  <tr> 
   <td>basePath</td> 
   <td>基本路径可以不配置</td> 
  </tr> 
  <tr> 
   <td>position</td> 
   <td>如果配置多个Api 想改变显示的顺序位置</td> 
  </tr> 
  <tr> 
   <td>produces</td> 
   <td>For example, "application/json, application/xml"</td> 
  </tr> 
  <tr> 
   <td>consumes</td> 
   <td>For example, "application/json, application/xml"</td> 
  </tr> 
  <tr> 
   <td>protocols</td> 
   <td>Possible values: http, https, ws, wss.</td> 
  </tr> 
  <tr> 
   <td>authorizations</td> 
   <td>高级特性认证时配置</td> 
  </tr> 
  <tr> 
   <td>hidden</td> 
   <td>配置为true 将在文档中隐藏</td> 
  </tr> 
  <tr> 
   <td>response</td> 
   <td>返回的对象</td> 
  </tr> 
  <tr> 
   <td>responseContainer</td> 
   <td>这些对象是有效的 "List", "Set" or "Map".，其他无效</td> 
  </tr> 
  <tr> 
   <td>httpMethod</td> 
   <td>"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"</td> 
  </tr> 
  <tr> 
   <td>code</td> 
   <td>http的状态码 默认 200</td> 
  </tr> 
  <tr> 
   <td>extensions</td> 
   <td>扩展属性</td> 
  </tr> 
 </tbody> 
</table>

在SpringMvc中的配置如下：

@RequestMapping(value = "/order/{orderId}", method = GET)
      @ApiOperation(
          value = "Find purchase order by ID",
          notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
          response = Order.class,
          tags = { "Pet Store" })
       public ResponseEntity<Order> getOrderById(@PathVariable("orderId") String orderId)
          throws NotFoundException {
        Order order = storeData.get(Long.valueOf(orderId));
        if (null != order) {
          return ok(order);
        } else {
          throw new NotFoundException(404, "Order not found");
        }
      }

3. ApiParam标记

ApiParam请求属性,使用方式：

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

与Controller中的方法并列使用。

属性配置：

<table> 
 <thead> 
  <tr> 
   <th>属性名称</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>name</td> 
   <td>属性名称</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td>属性值</td> 
  </tr> 
  <tr> 
   <td>defaultValue</td> 
   <td>默认属性值</td> 
  </tr> 
  <tr> 
   <td>allowableValues</td> 
   <td>可以不配置</td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td>是否属性必填</td> 
  </tr> 
  <tr> 
   <td>access</td> 
   <td>不过多描述</td> 
  </tr> 
  <tr> 
   <td>allowMultiple</td> 
   <td>默认为false</td> 
  </tr> 
  <tr> 
   <td>hidden</td> 
   <td>隐藏该属性</td> 
  </tr> 
  <tr> 
   <td>example</td> 
   <td>举例子</td> 
  </tr> 
 </tbody> 
</table>

在SpringMvc中的配置如下：

public ResponseEntity<Order> getOrderById(
          @ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true)
          @PathVariable("orderId") String orderId)

4. ApiResponse

ApiResponse：响应配置，使用方式：

@ApiResponse(code = 400, message = "Invalid user supplied")

与Controller中的方法并列使用。 属性配置：

<table> 
 <thead> 
  <tr> 
   <th>属性名称</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>code</td> 
   <td>http的状态码</td> 
  </tr> 
  <tr> 
   <td>message</td> 
   <td>描述</td> 
  </tr> 
  <tr> 
   <td>response</td> 
   <td>默认响应类 Void</td> 
  </tr> 
  <tr> 
   <td>reference</td> 
   <td>参考ApiOperation中配置</td> 
  </tr> 
  <tr> 
   <td>responseHeaders</td> 
   <td>参考 ResponseHeader 属性配置说明</td> 
  </tr> 
  <tr> 
   <td>responseContainer</td> 
   <td>参考ApiOperation中配置</td> 
  </tr> 
 </tbody> 
</table>

在SpringMvc中的配置如下：

@RequestMapping(value = "/order", method = POST)
      @ApiOperation(value = "Place an order for a pet", response = Order.class)
      @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
      public ResponseEntity<String> placeOrder(
          @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {
        storeData.add(order);
        return ok("");
      }

5. ApiResponses

ApiResponses：响应集配置，使用方式：

@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

与Controller中的方法并列使用。 属性配置：

<table> 
 <thead> 
  <tr> 
   <th>属性名称</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>多个ApiResponse配置</td> 
  </tr> 
 </tbody> 
</table>

在SpringMvc中的配置如下：

6. ResponseHeader

> 响应头设置，使用方法

@ResponseHeader(name="head1",description="response head conf")

与Controller中的方法并列使用。 属性配置：

<table> 
 <thead> 
  <tr> 
   <th>属性名称</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>name</td> 
   <td>响应头名称</td> 
  </tr> 
  <tr> 
   <td>description</td> 
   <td>头描述</td> 
  </tr> 
  <tr> 
   <td>response</td> 
   <td>默认响应类 Void</td> 
  </tr> 
  <tr> 
   <td>responseContainer</td> 
   <td>参考ApiOperation中配置</td> 
  </tr> 
 </tbody> 
</table>

在SpringMvc中的配置如下：

@ApiModel(description = "群组")

7. 其他

*  @ApiImplicitParams：用在方法上包含一组参数说明；
 *  @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
    
     *  paramType：参数放在哪个地方(这个是非常重要的，单个使用ApiParam经过测试，你想把参数放到query中，但实际ApiParam认为你的参数是在body中，所以在这种情况下，只能使用ApiImplicitParams)
     *      @ApiOperation(value = "互通组版本获取部门人员信息")
                @RequestMapping(value = "/v2/eoa/interflow/getUserAndDeptInfo.do", method = RequestMethod.GET)
                @ApiImplicitParams({
                        @ApiImplicitParam(name = "companyId", defaultValue = "企业id", required = true, paramType = "query", dataType = "int"),
                        @ApiImplicitParam(name = "deptId", defaultValue = "部门id", required = true, paramType = "query", dataType = "int"),
                        @ApiImplicitParam(name = "keyword", defaultValue = "搜索关键字", paramType = "query", dataType = "string")
                }
                )
        
            /**
             * The parameter type of the parameter.
             * <p>
             * Valid values are {@code path}, {@code query}, {@code body},
             * {@code header} or {@code form}.
             */
            String paramType() default "";
     *  name：参数代表的含义
     *  value：参数名称
     *  dataType： 参数类型，有String/int，无用
     *  required ： 是否必要
     *  defaultValue：参数的默认值
 *  @ApiResponses：用于表示一组响应；
 *  @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息；
    
     *  code： 响应码(int型)，可自定义
     *  message：状态码对应的响应信息
 *  @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候；
 *  @ApiModelProperty：描述一个model的属性。

[https_www.jianshu.com_p_12f4394462d5]: https://www.jianshu.com/p/12f4394462d5