跳到主要内容

Swagger-SwaggerDefinition 注解

1. 前言​

本节会继续结合一个用户接口相关类来给大家介绍 Swagger 中的另一个注解 SwaggerDefinition 注解及所提供的常用属性。

SwaggerDefinition 注解在实际开发中用的非常少了，尽管他提供了很多属性，但是在绝大多数情况下可以通过配置类解决的问题都不会用 SwaggerDefinition 注解。

所以大家在学习 SwaggerDefinition 注解的时候，只需要掌握基本定义和基本用法即可，由于篇幅有限，我只会选取最重要的属性来给大家截图演示，那些基本不用的就不再截图演示了。

重点讲解的属性：host 、basePath 、tags 、 externalDocs 。

2. 什么是 SwaggerDefinition 注解 ？​

SwaggerDefinition 注解是作用在接口类上面的注解，其主要是用来给 Swagger 生成的 UI 界面（下称 swagger-ui 界面）做一些额外的描述。

SwaggerDefinition 注解提供了丰富的属性来允许我们自定义 swagger-ui 界面的描述信息，包括界面访问地址、界面版本等。

下面我们来看一下 SwaggerDefinition 注解中都有哪些常用的属性。

3. SwaggerDefinition 注解主要属性汇总​

属性名称属性类型默认值作用
host()String空swagger-ui 界面访问主机
basePath()String空接口访问基本路径
tags()Tag[]@Tag(name = “”)定义全局接口分组类型
externalDocs()ExternalDocs@ExternalDocs(url = “”)定义接口中参方法或参数额外描述文档地址

4. 属性详解​

4.1 host() 和 basePath() 属性​

定义：

host 属性就是描述 swagger-ui 界面的访问主机，或者说是 Ip 地址，即如果，我想访问 Swagger 为我们生成的 swagger-ui 界面，所需要在浏览器地址栏中输入的地址信息。

basePath 属性就是描述 swagger-ui 界面的完整访问地址，他需要依赖 host 属性。

使用方法：

在 SwaggerDefinition 注解中，声明 host 和 basePath属性的值即可。

例如，我想让 swagger-ui 界面在本地就可以访问，那么我们可以这样描述 host 属性： host = “localhost”, 而 basePath 属性可以这样描述： basePath = “localhost:9001”，这样我们就能很清楚的知道 swagger-ui 界面所在的位置了（现在你不需要理解业务代码代表什么意思，重点看接口类上使用的注解及属性即可，下同）。

@SwaggerDefinition(host = "localhost", basePath = "localhost:9001")
public class UserController{
    // do something...
}

代码解释：

第 1 行，我们在 UserController 用户接口类的上方，使用了 @SwaggerDefinition 注解的 host 属性和 basePath 属性来规定 swagger-ui 界面的生成位置。

显示结果：

可以看到，在用红框圈起来的地方，就是我们使用 host 属性和 basePath 属性所描述的 swagger-ui 界面的访问路径了。

Tips ：

  1. host 属性和 basePath 属性的区别在于：前者只是定义了 swagger-ui 界面的访问 Ip 地址，如果没有端口的限制，则可以直接访问；而后者则是定义了 swagger-ui 界面的完整位置，其中就包括了端口的存在。
  2. 在实际开发工作中，往往不需要使用这两个属性来专门的定义 swagger-ui 的访问路径，因为 Swagger 会默认获取项目中通过配置类来定义的地址信息，使用这两个属性就多此一举了。

4.2 tags() 属性​

定义：

该属性就是对项目中所有的接口，添加分组类型描述，即在全局层面定义接口的所属分组类型，类似于 @Api 和 @ApiOperaiton 注解中的 tags 属性。

使用方法：

在 SwaggerDefinition 注解中声明 tags 的值即可，如果没有描述则默认值为空。例如，就用户接口类而言，该接口类属于用户业务分组，所以我们将 tags 的值描述为‘用户’或者‘user’，这样我们就能很清楚的看到这个接口类是属于用户业务组的，如下代码段所示。

@SwaggerDefinition(tags = { @Tag(name = "user") })
public class UserController{
    // do something...
}

代码解释：

第 1 行，我们在 UserController 接口类的上方使用了 @SwaggerDefinition 注解的 tags 属性来描述该接口类所属的业务分组。

Tips ： 该属性在实际工作中基本很少使用，如果有的接口需要进行分组，那么可以直接使用 @Api 注解的 tags 属性来描述，大家只需要知道 SwaggerDefinition 注解存在一个 tags 属性即可。

4.3 externalDocs() 属性​

定义：

如果接口方法或其中的参数存在额外的文档描述，则可以通过该属性进行绑定，即为接口方法或其中的参数提供额外的文档支持。

使用方法：

在 SwaggerDefinition 注解中声明 externalDocs 的值即可。例如，如果我想添加一个额外的文档地址，那么我可以这样写 externalDocs = @ExternalDocs(url = “localhost:8000”)，如下代码段所示。

@SwaggerDefinition(externalDocs = @ExternalDocs(url = "localhost:8000"))
public class UserController{
    // do something...
}

代码解释：

第 1 行，我们在 UserController 接口类的上方使用了 @SwaggerDefinition 注解的 externalDocs 属性来描述额外文档的地址信息。

Tips ： externalDocs 属性很少使用，在实际工作中，如果有的接口方法和接口方法中的参数有其他额外的描述话，就直接使用 @ApiOperation 来一并说明了，并不会单独使用一个注解再来说明。

5. 小结​

本小节对 Swagger 中的 SwaggerDefinition 注解及其该注解的常用属性做了详细的讲解，针对 SwaggerDefinition 注解中，经常在实际项目开发中使用的属性，采用图文并茂的方式进行了重点介绍和应用剖析，对于一些在实际项目开发中使用基本很少的注解做了概要讲解。

SwaggerDefinition 虽是 Swagger 众多注解中的一个注解，但在实际开发工作中其存在的价值值得我们重新考量。