SwaggerAPI注解详解,以及注解常用参数配置

曾经终败给现在 2022-06-01 11:17 275阅读 0赞

官网github地址：[https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X][https_github.com_swagger-api_swagger-core_wiki_Annotations-1.5.X]

## 注解 ##

### @Api： ###

作用在类上，用来标注该类具体实现内容。表示标识这个类是swagger的资源 。  
参数：  
1. tags：可以使用tags()允许您为操作设置多个标签的属性，而不是使用该属性。  
2. description：可描述描述该类作用。

### @ApiImplicitParam： ###

作用在方法上，表示单独的请求参数  
参数：  
1. name ：参数名。  
2. value ： 参数的具体意义，作用。  
3. required ： 参数是否必填。  
4. dataType ：参数的数据类型。  
5. paramType ：查询参数类型，这里有几种形式：

<table> 
 <thead> 
  <tr> 
   <th>类型</th> 
   <th align="center">作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>path</td> 
   <td align="center">以地址的形式提交数据</td> 
  </tr> 
  <tr> 
   <td>query</td> 
   <td align="center">直接跟参数完成自动映射赋值</td> 
  </tr> 
  <tr> 
   <td>body</td> 
   <td align="center">以流的形式提交 仅支持POST</td> 
  </tr> 
  <tr> 
   <td>header</td> 
   <td align="center">参数在request headers 里边提交</td> 
  </tr> 
  <tr> 
   <td>form</td> 
   <td align="center">以form表单的形式提交 仅支持POST</td> 
  </tr> 
 </tbody> 
</table>

**在这里我被坑过一次**：当我发POST请求的时候，当时接受的整个参数，不论我用body还是query，后台都会报Body Missing错误。这个参数和SpringMvc中的@RequestBody冲突，索性我就去掉了paramType，对接口测试并没有影响。

### @ApiImplicitParams： ###

用于方法，包含多个 @ApiImplicitParam：  
例：

@ApiImplicitParams({
                @ApiImplicitParam(name = "id", value = "book's name", required = true, dataType = "Long", paramType = "query"),
                @ApiImplicitParam(name = "date", value = "book's date", required = false, dataType = "string", paramType = "query")})

### @ApiModel： ###

用于类，表示对类进行说明，用于参数用实体类接收；

### @ApiModelProperty： ###

用于方法，字段 ，表示对model属性的说明或者数据操作更改  
例：

@ApiModel(value = "User", description = "用户")
        public class User implements Serializable{ 
    
        private static final long serialVersionUID = 1546481732633762837L;
    
        /** * 用户ID */
        @ApiModelProperty(value = "用户ID", required = true)
        @NotEmpty(message = "{id.empty}", groups = {Default.class,New.class,Update.class})
        protected String id;
    
        /** * code/登录帐号 */
        @ApiModelProperty(value = "code/登录帐号")
        @NotEmpty(message = "{itcode.empty}", groups = {Default.class,New.class,Update.class})
        protected String itcode;
    
        /** * 用户姓名 */
        @ApiModelProperty(value = "用户姓名")
        @NotEmpty(message = "{name.empty}", groups = {Default.class,New.class,Update.class})
        protected String name;

### @ApiOperation： ###

用于方法，表示一个http请求的操作 。

@ApiOperation(value = "获取图书信息", notes = "获取图书信息", response = Book.class, responseContainer = "Item", produces = "application/json")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "id", value = "book's name", required = true, dataType = "Long", paramType = "query"),
                @ApiImplicitParam(name = "date", value = "book's date", required = false, dataType = "string", paramType = "query")})
        @RequestMapping(value = "/{id}", method = RequestMethod.GET)
        @ResponseBody
        public Book getBook(@PathVariable Long id, String date) {
            return books.get(id);
        }

### @ApiResponse： ###

用于方法，描述操作的可能响应。

### @ApiResponses： ###

用于方法，一个允许多个ApiResponse对象列表的包装器。  
例：

@ApiResponses(value = { 
                @ApiResponse(code = 500, message = "2001:因输入数据问题导致的报错"), @ApiResponse(code = 500, message = "403:没有权限"), @ApiResponse(code = 500, message = "2500:通用报错（包括数据、逻辑、外键关联等，不区分错误类型）")})

### @ApiParam： ###

用于方法，参数，字段说明，表示对参数的添加元数据（说明或是否必填等）

### @Authorization： ###

声明要在资源或操作上使用的授权方案。

### @AuthorizationScope： ###

介绍一个OAuth2授权范围。

### @ResponseHeader： ###

响应头设置，使用方法。

[https_github.com_swagger-api_swagger-core_wiki_Annotations-1.5.X]: https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X