API注解使用方法

Api注解不是Spring自带的，他是swagger里面的，代码编写的时候需要在pom文件中引入相关swagger的依赖

​
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>
​

以下列举了常用的一些注解：

1. @Api：用在请求的类上，表示对类的说明

   tags="说明该类的作用，可以在UI界面上看到的注解"

   value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

2. @ApiOperation 用在请求的方法上，说明方法的用途、作用 @ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response =“接口返回参数类型”, notes = “接口发布说明”；

1. @ApiResponses：用在请求的方法上，表示一组响应

   @ApiResponse：用在@ApiResponses中，一般用于表达一个错误或正确的响应信息

   code：数字，例如400

   message：信息，例如"请求参数没填好"

   response：抛出异常的类

   @ApiResponses({ @ApiResponse(code = 0, message = "请求成功"), @ApiResponse(code = 1, message = "请求失败") })

2. @ApiModelProperty：用在属性上，描述响应类的属性

   value–字段说明；name–重写属性名字；dataType–重写属性类型；required–是否必填；example–举例说明；hidden–隐藏

   @ApiModelProperty(value = "请求返回code说明，0-成功，1-失败",required = true,example = "0")

3. @ApiImplicitParams：用在请求的方法上，表示一组参数说明

   @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

   name：参数名；value：参数的汉字说明、解释；required：参数是否必须传

   paramType：参数放在哪个地方

   · header --> 请求参数的获取：@RequestHeader

   · query --> 请求参数的获取：@RequestParam

   · path（用于restful接口）--> 请求参数的获取：@PathVariable

   · body（不常用）

   · form（不常用）

   dataType：参数类型，默认String，其它值dataType="Integer"

   defaultValue：参数的默认值

4. @ApiModel：用于响应类上，表示一个返回响应数据的信息

   （这种一般用在post创建的时候，使用@RequestBody这样的场景

   请求参数无法使用@ApiImplicitParam注解进行描述的时候）

5. @ApiIgnore：添加在处理请求的方法的参数上，当某个参数不需要显示在API文档中，则需要在参数上添加此注解，例如HttpServletRequest、HttpSession等