之前我们已经学习Swagger的基本使用，考虑到胖友能够更好的使用，我们来一个一个注解了解。

在 swagger-annotations 库中，在 io.swagger.annotations 包路径下，提供了我们会使用到的所有 Swagger 注解。Swagger 提供的注解还是比较多的，大多数场景下，只需要使用到我们在 「SwaggerFrontController」 中用到的注解。

@Api

@Api 注解，添加在 Controller 类上，标记它作为 Swagger 文档资源。

@Controller
@RequestMapping("/swagger/front")
@Api(tags = "前台测试 API 接口")
public class SwaggerFrontController {
}

@Api 注解的常用属性，如下：

• tags 属性：用于控制 API 所属的标签列表。[] 数组，可以填写多个。
• 可以在一个 Controller 上的 @Api 的 tags 属性，设置多个标签，那么这个 Controller 下的 API 接口，就会出现在这两个标签中。
• 如果在多个 Controller 上的 @Api 的 tags 属性，设置一个标签，那么这些 Controller 下的 API 接口，仅会出现在这一个标签中。
• 本质上，tags 就是为了分组 API 接口，和 Controller 本质上是一个目的。所以绝大数场景下，我们只会给一个 Controller 一个唯一的标签。例如说，SwaggerFrontController的 tags 设置为 "前台测试 API 接口" 。

@Api 注解的不常用属性，如下：

• produces 属性：请求请求头的可接受类型( Accept )。如果有多个，使用 , 分隔。
• consumes 属性：请求请求头的提交内容类型( Content-Type )。如果有多个，使用 , 分隔。
• protocols 属性：协议，可选值为 "http"、"https"、"ws"、"wss" 。如果有多个，使用 , 分隔。
• authorizations 属性：授权相关的配置，[] 数组，使用 @Authorization 注解。
• hidden 属性：是否隐藏，不再 API 接口文档中显示。

@Api 注解的废弃属性，不建议使用，有 value、description、basePath、position 。

@ApiOperation

@ApiOperation 注解，添加在 Controller 方法上，标记它是一个 API 操作。

示例如下：

    @ResponseBody
    @PostMapping("/frontTest")
    @ApiOperation(value = "测试", notes = "目前仅用于测试使用")
    @ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024"),
    public String frontTest(@RequestParam("id") Integer id) {
        return "用户ID=" + id;
    }

效果如下：

@ApiOperation 注解的常用属性，如下：

• value 属性：API 操作名。
• notes 属性：API 操作的描述。

@ApiOperation 注解的不常用属性，如下：

• tags 属性：和 @API 注解的 tags 属性一致。
• nickname 属性：API 操作接口的唯一标识，主要用于和第三方工具做对接。
• httpMethod 属性：请求方法，可选值为 GET、HEAD、POST、PUT、DELETE、OPTIONS、PATCH 。因为 Swagger 会解析 SpringMVC 的注解，所以一般无需填写。
• produces 属性：和 @API 注解的 produces 属性一致。
• consumes 属性：和 @API 注解的 consumes 属性一致。
• protocols 属性：和 @API 注解的 protocols 属性一致。
• authorizations 属性：和 @API 注解的 authorizations 属性一致。
• hidden 属性：和 @API 注解的 hidden 属性一致。
• response 属性：响应结果类型。因为 Swagger 会解析方法的返回类型，所以一般无需填写。
• responseContainer 属性：响应结果的容器，可选值为 List、Set、Map 。
• responseReference 属性：指定对响应类型的引用。这个引用可以是本地，也可以是远程。并且，当设置了它时，会覆盖 response 属性。说人话，就是可以忽略这个属性，哈哈哈。
• responseHeaders 属性：响应头，[] 数组，使用 @ResponseHeader 注解。
• code 属性：响应状态码，默认为 200 。
• extensions 属性：拓展属性，[] 属性，使用 @Extension 注解。
• ignoreJsonView 属性：在解析操作和类型，忽略 JsonView 注释。主要是为了向后兼容。

@ApiOperation 注解的废弃属性，不建议使用，有 position 。

@ApiImplicitParam

@ApiImplicitParam 注解，添加在 Controller 方法上，声明每个请求参数的信息。

示例如下：

    @ResponseBody
    @PostMapping("/frontTest")
    @ApiOperation(value = "测试", notes = "目前仅用于测试使用")
    @ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024"),
    public String frontTest(@RequestParam("id") Integer id) {
        return "用户ID=" + id;
    }

效果如下：

@ApiImplicitParam 注解的常用属性，如下：

• name 属性：参数名。
• value 属性：参数的简要说明。
• required 属性：是否为必传参数。默认为 false 。
• dataType 属性：数据类型，通过字符串 String 定义。
• dataTypeClass 属性：数据类型，通过 dataTypeClass 定义。在设置了 dataTypeClass 属性的情况下，会覆盖 dataType 属性。推荐采用这个方式。
• paramType 属性：参数所在位置的类型。有如下 5 种方式："path" 值：对应 SpringMVC 的 @PathVariable 注解。【默认值】"query" 值：对应 SpringMVC 的 @PathVariable 注解。"body" 值：对应 SpringMVC 的 @RequestBody 注解。"header" 值：对应 SpringMVC 的 @RequestHeader 注解。"form" 值：Form 表单提交，对应 SpringMVC 的 @PathVariable 注解。 绝大多数情况下，使用 "query" 值这个类型即可。
• example 属性：参数值的简单示例。
• examples 属性：参数值的复杂示例，使用 @Example 注解。

@ApiImplicitParam 注解的不常用属性，如下：

• defaultValue 属性：默认值。
• allowableValues 属性：允许的值。如果要设置多个值，有两种方式：数组方式，即 {value1, value2, value3} 。例如说，{1, 2, 3} 。范围方式，即 [value1, value2] 或 [value1, value2) 。例如说 [1, 5] 表示 1 到 5 的所有数字。如果有无穷的，可以使用 (-infinity, value2] 或 [value1, infinity) 。
• allowEmptyValue 属性：是否允许空值。
• allowMultiple 属性：是否允许通过多次传递该参数来接受多个值。默认为 false 。
• type 属性：搞不懂具体用途，对应英文注释为 Adds the ability to override the detected type 。
• readOnly 属性：是否只读。
• format 属性：自定义的格式化。
• collectionFormat 属性：针对 Collection 集合的，自定义的格式化。

当我们需要添加在方法上添加多个 @ApiImplicitParam 注解时，可以使用 @ApiImplicitParams 注解中添加多个。示例如下：

    @ResponseBody
    @PostMapping("/frontTest")
    @ApiOperation(value = "测试", notes = "目前仅用于测试使用")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024"),
            @ApiImplicitParam(name = "name", value = "用户名称", paramType = "query", dataTypeClass = String.class, required = true, example = "莫拉塔")
    })
    public String frontTest(@RequestParam("id") Integer id,@RequestParam("name") String name) {
        return "用户ID=" + id + ",用户名称=" + name;
    }

效果如下：

@ApiModel

@ApiModel 注解，添加在 POJO 类，声明 POJO 类的信息。而在 Swagger 中，把这种 POJO 类称为 Model 类。所以，我们下文就统一这么称呼。

示例如下：

@ApiModel("用户VO")
public class UserV0 {
}

@ApiModel 注解的常用属性，如下：

• value 属性：Model 名字。
• description 属性：Model 描述。

@ApiModel 注解的不常用属性，如下：

• parent 属性：指定该 Model 的父 Class 类，用于继承父 Class 的 Swagger 信息。
• subTypes 属性：定义该 Model 类的子类 Class 们。
• discriminator 属性：搞不懂具体用途，对应英文注释为 Supports model inheritance and polymorphism.
• reference 属性：搞不懂具体用途，对应英文注释为 Specifies a reference to the corresponding type definition, overrides any other metadata specified

@ApiModelProperty

@ApiModelProperty 注解，添加在 Model 类的成员变量上，声明每个成员变量的信息。

示例如下：

@ApiModel("用户VO")
@Data
public class UserV0 {
    @ApiModelProperty(value = "用户编号", required = true, example = "1024")
    private Integer id;
    @ApiModelProperty(value = "账号", required = true, example = "莫拉塔")
    private String username;
}

效果如下：

@ApiModelProperty 注解的常用属性，如下：

• value 属性：属性的描述。
• dataType 属性：和 @ApiImplicitParam 注解的 dataType 属性一致。不过因为 @ApiModelProperty 是添加在成员变量上，可以自动获得成员变量的类型。
• required 属性：和 @ApiImplicitParam 注解的 required 属性一致。
• example 属性：@ApiImplicitParam 注解的 example 属性一致。

@ApiModelProperty 注解的不常用属性，如下：

• name 属性：覆盖成员变量的名字，使用该属性进行自定义。
• allowableValues 属性：和 @ApiImplicitParam 注解的 allowableValues 属性一致。
• position 属性：成员变量排序位置，默认为 0 。
• hidden 属性：@ApiImplicitParam 注解的 hidden 属性一致。
• accessMode 属性：访问模式，有 AccessMode.AUTO、AccessMode.READ_ONLY、AccessMode.READ_WRITE 三种，默认为 AccessMode.AUTO 。
• reference 属性：和 @ApiModel 注解的 reference 属性一致。
• allowEmptyValue 属性：和 @ApiImplicitParam 注解的 allowEmptyValue 属性一致。
• extensions 属性：和 @ApiImplicitParam 注解的 extensions 属性一致。

@ApiModelProperty 注解的废弃属性，不建议使用，有 readOnly 。

@ApiResponse

在大多数情况下，我们并不需要使用 @ApiResponse 注解，因为我们会类似 SwaggerFrontController#frontTestUser(id) 方法这个接口，返回一个 Model 即可。所以 @ApiResponse 注解，就简单讲解，嘿嘿。

@ApiResponse 注解，添加在 Controller 类的方法上，声明每个响应参数的信息。

@ApiResponse 注解的属性，基本已经被 @ApiOperation 注解所覆盖，如下：

• message 属性：响应的提示内容。
• code 属性：和 @ApiOperation 注解的 code 属性一致。
• response 属性：和 @ApiOperation 注解的 response 属性一致。
• reference 属性：和 @ApiOperation 注解的 responseReference 属性一致。
• responseHeaders 属性：和 @ApiOperation 注解的 responseHeaders 属性一致。
• responseContainer 属性：和 @ApiOperation 注解的 responseContainer 属性一致。
• examples 属性：和 @ApiOperation 注解的 examples 属性一致。

当我们需要添加在方法上添加多个 @ApiResponse 注解时，可以使用 @ApiResponses 注解中添加多个。

至此，我们已经了解完 Swagger 项目中提供的主要注解。如果想要看到更多的 Swagger 的使用示例，可以看看艿艿开源的 onemall 项目。

咳咳咳，整理 Swagger 注解的每个属性，真的是花费时间。如果有哪个解释不到位，请一定给我留言，我去优化和调整下，嘻嘻。[爱慕][爱慕][爱慕]

Tags：apiimplicitparam注解用法