Swagger – 注解组合实战

1. 前言

写到这里呢，在 Swagger 中的注解及其属性都给大家介绍完毕了，那么我们现在需要掌握的就是在真正的项目中对这些注解进行实操，达到真正会使用的目的。

在前面所讲课程中，课程内容都是针对 Swagger 中的一个注解进行介绍，并不会介绍各个注解间都有一个什么样的关系，以及各个主键间如何搭配或者配合使用。

针对上述问题，本节会结合几个在 Swagger 中使用频率非常高的注解进行组合式讲解，无论是两个注解间的搭配使用，还是多个注解间的配合使用，我都会在本节中进行详细介绍，小伙伴们赶快打击精神来学习吧！

本节会结合以下几个常用注解进行组合实战讲解：

• @Api 注解；
• @ApiOperation 注解；
• @ApiParam 注解；
• @ApiImplicitParams 注解；
• @ApiResponses 注解；
• @ApiModel 注解；
• @ApiModelProperty 注解。

本节主要内容有：

• @Api 注解与 @ApiOperation 注解组合实战；
• @ApiParam 注解与 @ApiImplicitParams 注解组合实战；
• @ApiModel 注解与 @ApiModelProperty 注解组合实战；
• @ApiImplicitParams 注解与 @ApiResponses 注解组合实战。

希望大家在学习本节过程中能够真正掌握多个注解间配合使用的方法，做到融会贯通，随手拈来。

2. @Api 注解与 @ApiOperation 注解组合实战

实操目标： 实现接口类与接口类中所有接口方法的准确描述。

实现思路：

第一步：使用 @Api 注解对接口类进行描述。

第二步：使用 @ApiOperation 注解对接口类中所有接口方法进行描述。

第三步：查看配置结果。

实现代码：

接口类：

@Api(value = "user-controller", description = "用户业务相关接口类", tags = {"user"})
public class UserController{
    // do something...
}

代码解释：

第 1 行，我们在接口类的上方使用 @Api 注解的 value 属性和 description 属性以及 tags 属性为接口类添加了一些文字描述信息来对接口类进行一些必要的描述。

其中，value 属性表示接口类在 Swagger 界面上所显示的名称，description 表示对接口类的描述，tags 属性则表示对该接口类添加一个分组，表明该接口类是属于哪一组的。

实现代码：

接口方法：

@ApiOperation(name = "user", value = "用户登录对象", tags = {"user"})
public ServerResponse<User> login(HttpSession session, User user){
    // do something...
}

代码解释：

第 1 行，我们在接口方法上使用 @ApiOperation 注解的 name 和 value 属性来对接口方法中的参数进行说明，使用 tags 属性来对该接口方法进行一个分组。

显示结果：

可以看到，在第一个标签的位置，从左到右分别表示对该用户相关接口类的分组名称 user ， 以及对该用户接口类的说明：‘用户相关接口类’。

在第二个标签位置，表示对用户登录接口方法中的 user 对象类型的参数的说明：‘用户登录对象’。

Tips ：

1. 如果在一个接口类中，我们使用了 @Api 注解的 tags 属性来对该接口分组，那么该接口类中的所有接口都将默认被分到该类中，除非我们使用 @ApiOperation 注解的 tags 属性为接口方法重新指定了另外一个分组。
2. 在实际项目开发中，@ApiOperation 注解与 @Api 注解经常这样搭配起来用，可以说，只要使用 Swagger 那么必定会这么用，这种使用方法同学们必须掌握。
3. 不同版本的 Swagger 显示可能会有不同，这点请同学们注意。

3. @ApiParam 注解与 @ApiImplicitParams 注解组合实战

实操目标： 实现对接口方法中多个参数的准确描述，同时体会 @ApiParam 注解与 @ApiImplicitParams 注解使用时的差异。

实现思路：

第一步：使用 @ApiParam 注解对接口方法中的一个参数进行描述，并查看其描述结果。

第二步：使用 @ApiImplicitParams 注解对接口方法中的多个参数进行描述，并查看其描述结果。

第三步：总结对比两个注解使用时的差异。

实现代码：

@ApiParam 注解作用在接口方法上时：

@ApiParam(name = "session", value = "用户session数据")
public ServerResponse<User> login(HttpSession session, User user){
    // do something...
}

显示结果：

可以看到，在红色框框起来的位置并没有看到关于 session 参数的说明 (正常的话会在红框中出现对 session 参数的说明)。

• @ApiImplicitParams 注解作用在接口方法上时

  @ApiImplicitParams(value = { @ApiImplicitParam(name = "session", value = "用户session数据"),
  @ApiImplicitParam(name = "user", value = "用户登录对象参数") })
  public ServerResponse login(HttpSession session, User user){
  // do something…
  }

显示结果：

可以看到，在用红色框框起来的位置分别显示出了使用 @ApiImplicitParams 注解对参数所描述的信息，并且是多个参数。

Tips ：

1. 如果你使用的是 Swagger 的低版本且只需要对接口中的一个参数进行描述，则可以使用 @ApiParam 注解；如果你使用的是 Swagger 高版本且需要对多个接口中的参数进行描述，则应该首先考虑使用 @ApiImplicitParams 注解。
2. 在实际项目开发中，如果需要对接口中的参数进行描述，那么无论需要描述几个参数，都应该首先考虑使用 @ApiImplicitParams 注解，因为他的兼容性是最好的。
3. 在 Swagger 高版本中，@ApiParam 注解并不会有任何效果，而 @ApiImplicitParams 注解则替代了 @ApiParam 注解的作用效果，并且支持对多个参数同时进行描述，这点需要同学们注意。

4. @ApiModel 注解与 @ApiModelProperty 注解组合实战

实操目标： 以用户实体类为例，实现对用户业务实体 (Entity) 的准确描述，以及对实体中各个字段的准确描述，体会 @ApiModel 注解与 @ApiModelProperty 注解作用效果的不同之处。

实现思路：

第一步：使用 @ApiModel 注解对实体类进行描述。

第二步：使用 @ApiModelProperty 注解对实体类中的所有字段参数进行描述。

第三步：查看配置结果，体会两个注解作用效果的不同之处。

实现代码：

实体类：

@ApiModel(value = "用户实体，存储用户相关字段")
public class User {
    // do something...
}

代码解释：

第 1 行，我们在用户实体类的上方使用 @ApiModel 注解的 value 属性对实体类进行描述：用户实体，存储用户相关字段。

实体类中的字段：

@ApiModelProperty(name = "id", value = "用户Id", required = true)
private Integer id;
@ApiModelProperty(name = "username", value = "用户名", required = true)
private String username;
@ApiModelProperty(name = "idCard", value = "用户身份证号", required = true)
private String idCard;
@ApiModelProperty(name = "phone", value = "用户手机号码", required = true)
private String phone;

代码解释：

第 1、3、5、7 行，我们使用 @ApiModelProperty 注解的 name 属性、value 属性、required 属性分别定义了字段的名称，内容以及是否必传。

显示结果：

可以看到，在用蓝色框框起来的位置就是我们使用 @ApiModel 对用户实体类所描述的信息，红色框框起来的位置就是使用 @ApiModelProperty 注解对用户实体类中所有的字段所描述的信息。

值得注意的是，在描述字段时，allowEmptyValue 这个属性我们并没有显式的拿来使用，但是 Swagger 还是给我都显示出来了，这是因为 Swagger 默认会将所有字段的 allowEmptyValue 属性置位 false ，表示字段的值可以为空。

Tips ： 一定要注意上述两个注解所作用的效果，@ApiModel 是直接作用在实体类上的，@ApiModelProperty 是直接作用在实体类中所有参数上的，两者不要搞混。

5. @ApiImplicitParams 注解与 @ApiResponses 注解组合实战

实操目标： 以用户登录接口方法为例，实现对该方法中的参数添加描述信息的同时，对接口的返回状态码进行自定义描述。

实现思路：

第一步：使用 @ApiImplicitParams 注解对接口方法中的参数进行描述。

第二步：使用 @ApiResponses 注解对用户登录接口所返回的状态码添加自定义描述信息。

第三步：查看配置结果。

实现代码：

接口中的参数：

@ApiImplicitParams(value = { @ApiImplicitParam(name = "session", value = "用户session数据"),
@ApiImplicitParam(name = "user", value = "用户登录对象参数") })
public ServerResponse<User> login(HttpSession session, User user){
    // do something...
}

代码解释：

这段代码我们在前面已经介绍过了，显示效果请参考上述截图，这里不再赘述。

自定义接口返回状态码：

@ApiResponses(value = { 
  @ApiResponse(code = 601, message = "请求成功",
  @ApiResponse(code = 602, message = "请求失败"),
  @ApiResponse(code = 603, message = "参数传递非")})
public ServerResponse<User> login(HttpSession session, User user){
    // do something...
}

代码解释：

1-3 行，我们使用 @ApiResponses 注解对用户登录接口的返回状态码添加了多条自定义描述信息。

显示结果：

可以看到，601、602、603 及其右侧所对应的文字描述就是我们使用 @ApiResponses 注解所描述的信息了。

Tips ：

1. 在实际项目开发中，如果有需要对一个接口的返回状态码添加描述信息，则请在对接口中参数进行描述时一并添加，@ApiImplicitParams 注解和 @ApiResponses 注解经常一起使用。
2. @ApiResponses 注解的使用方法同学们一定要注意，他只有一个属性 value ，并没有其它额外的属性，在使用时一定要注意 value 属性所指定的方式。

6. 小结

本小节针对在 Swagger 中经常在项目开发中使用的几个注解做了进一步介绍，针对 Swagger 中不同注解搭配使用以及多注解组合使用的情况采用图文并茂的方式做了详细介绍和应用剖析，旨在帮助同学们在了解各个注解及其属性之后真正的可以将所学应用到真实的实际项目开发中。

因为本小节偏于实战，注重实操，所以各位同学在学习本小节时应该将本节中所涉及的代码跟着手动敲一遍，然后结合自己的项目或者自己创建的 Demo 来进行学习，这是掌握本节内容最快最直接的方式，也是为将来在项目中使用 Swagger 打下一定的基础。

本小节为 "Swagger 注解" 这一章节中的最后一篇文章，在本章中分别对 Swagger 中的注解做了详细介绍和应用剖析，针对在实际项目中使用频率很高的注解做了进一步的组合实操讲解，掌握本章节内容是学好 Swagger 的基础，所以请同学们在充分掌握本章内容之后再继续学习下面的内容。