章节索引 :

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 众多注解中的一个注解,但在实际开发工作中其存在的价值值得我们重新考量。