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 = “接口发布说明”；

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

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

code：数字，例如400

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

response：抛出异常的类

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

4、@ApiModelProperty：用在属性上，描述响应类的属性

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

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

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

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

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

paramType：参数放在哪个地方

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

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

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

· body（不常用）

· form（不常用）

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

defaultValue：参数的默认值

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

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

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