常用注解

1. @Api

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

@Api(tags="用户相关接口")
@RestController
@RequestMapping(value="/api/user")
public class UserController {}

参数说明：

2. @ApiParam

用在请求方法中，描述参数信息，使用方式：

@PostMapping(value="/login")
@ApiOperation(value = "登录", notes="根据用户名、密码登录")
public UserModel login(@ApiParam(name = "model", value = "用户信息Model") UserModel model){}

参数说明：

3. @ApiOperation

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

@PostMapping(value="/login")
@ApiOperation(value = "登录", notes="根据用户名、密码登入")
public ReturnBean login(String username, String password){}

参数说明：

4. @ApiImplicitParams，@ApiImplicitParam

• @ApiImplicitParams

  用在请求的方法上，表示一组参数说明。只有value一个属性，用来装多个@ApiImplicitParam

• @ApiImplicitParam

  用在 @ApiImplicitParams 注解中，对请求参数进行详细说明

  示例：

  @PostMapping(value="/login")
  @ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
  @ApiImplicitParams({
        @ApiImplicitParam(name = "username", value = "用户名", required = true, paramType = "query", dataType = "String"),
        @ApiImplicitParam(name = "password", value = "密码", required = true, paramType = "query", dataType = "String") 
  })
  public UserModel login(String username,String password){}
  

  参数说明：

  属性名	描述
  name	参数名，参数名称可以覆盖方法参数名称，路径参数(path)必须与方法参数一致
  value	参数的汉字说明、解释
  required	参数是否必须，默认为false
  paramType	参数放在哪个地方
  dataType	参数类型，默认string
  defaultValue	参数的默认值
  allowableValues	限制参数的可接受值。1.以逗号分隔的列表 2、范围值
  access	允许从API文档中过滤参数
  allowMultiple	指定参数是否可以通过具有多个事件接受多个值，默认为false
  example	单个参数示例
  examples	参数示例。仅适用于BodyParameters

  特别说明：

  1. paramType

     header： @RequestHeader(代码中接收注解)
     query： @RequestParam(代码中接收注解)
     path：用于restful接口，@PathVariable(代码中接收注解)
     body：JSON方式提交，也可以通过流的形式接收当前的请求数据（用 @RequestBody 之后流就会关闭了）
     form：以form表单的形式提交，仅支持POST（不常用）
     

  2. dataType

     // 官方说明：
     /**
     * The data type of the parameter.
     * <p>
     

  • This can be the class name or a primitive.
    */
    String dataType() default "";

  默认 string
  实测可选值为：
  string
  int
  float
  double
  boolean
  object(2.9.2版本有效)

  
  3. allowableValues
  
  - 以逗号分隔
  
    ```java
    @ApiImplicitParam(name = "state", value = "状态", paramType = "query", dataType = "int", allowableValues = "1,2,3")
    ```
  
  - 范围值(实测只在实体类属性中有效，方法参数中无效)
  
    ```java
    @ApiImplicitParam(name = "state", value = "状态", paramType = "query", dataType = "int", allowableValues = "range[1,10]")
  
    /*
    range[1,10]
    range[1,10)
    range(1,10)
    无穷使用 infinity 或 -infinity
    */
  
    // 官方说明：
    /**
     * Limits the acceptable values for this parameter.
     * <p>
     * There are three ways to describe the allowable values:
     * <ol>
     * <li>To set a list of values, provide a comma-separated list.
     * For example: {@code first, second, third}.</li>
     * <li>To set a range of values, start the value with "range", and surrounding by square
     * brackets include the minimum and maximum values, or round brackets for exclusive minimum and maximum values.
     * For example: {@code range[1, 5]}, {@code range(1, 5)}, {@code range[1, 5)}.</li>
     * <li>To set a minimum/maximum value, use the same format for range but use "infinity"
     * or "-infinity" as the second value. For example, {@code range[1, infinity]} means the
     * minimum allowable value of this parameter is 1.</li>
     * </ol>
     */
    String allowableValues() default "";
    ```
  
  
  
  

## 5. @ApiModel，@ApiModelProperty

• @ApiModel

用在实体类上，表示对类的说明（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用 @ApiImplicitParam注解进行描述的时候）

参数说明：

• @ApiModelProperty

  用在属性上，描述响应类的属性

  参数说明：

  属性名	描述
  value	此属性的简要说明
  name	允许覆盖属性名称
  allowableValues	限制参数的可接受值。1.以逗号分隔的列表 2、范围值
  access	允许从 API 文档中过滤属性
  notes	备注
  dataType	参数的数据类型。可以是类名或者参数名，会覆盖类的属性名称
  required	参数是否必，默认为false
  position	允许在类中对属性进行排序。默认为0
  hidden	允许在 Swagger 模型定义中隐藏该属性
  example	属性的示例
  readOnly	将属性设定为只读
  reference	指定对相应类型定义的引用，覆盖指定的任何参数值

示例：

@ApiModel(value = "登录用户信息")
public class UserDTO {
    @ApiModelProperty(value = "用户名")
    private String username;
}

6. @ApiResponses，@ApiResponse

• @ApiResponses

  用在请求的方法上，表示一组响应。只有value一个属性，用来装多个@ApiResponse

• @ApiResponse

  用在@ApiResponses中，一般用于表达一个错误的响应信息

  参数说明：

  属性名	描述
  code	HTTP 状态码
  message	错误信息
  response	响应类，默认Void.class
  reference	指定对相应类型定义的引用，覆盖指定的任何参数值
  responseContainer	声明包装的响应容器（返回对象类型）。有效值为 "List", "Set"，"Map"
  responseHeaders	响应头列表

示例：

@ResponseBody
@PostMapping(value="/update/{id}")
@ApiOperation(value = "修改用户信息", notes = "修改指定用户信息")
@ApiResponses({
    @ApiResponse(code=400,message="请求参数错误"),
    @ApiResponse(code=404,message="请求路径错误或不存在")
})
public ReturnBean update(@PathVariable String id, UserDTO user){}

7. @ResponseHeader

响应头设置，使用方法：

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

参数说明：

8. @ApiIgnore

@ApiIgnore 注解主要作用在方法上，类上，参数上。该注解只有一个 value 属性，用于描述忽略参数的原因。

当作用在方法上时，方法将被忽略；作用在类上时，整个类都会被忽略；作用在参数上时，单个具体的参数会被忽略。

注意：这里忽略的意思是 swagger-ui.html 上不会显示对应的接口信息

# Java # Swagger # Open API