网上关于 Spring Boot 中使用 Swagger 3 的有效文章真的很少，百度出来的基本全是 Swagger 2.X 的内容，或者打着 Swagger 3 的旗号，写着 2.X 的内容。因此我觉得有必要记录我在使用 Swagger 3（OpenAPI 3.0）的过程中的一些事项，希望能帮助到更多的人。

示例代码已上传到 GitHub：spring-boot-springfox-swagger3 。

OpenAPI 规范（OAS）为 RESTful API 定义了一个标准、与编程语言无关的 API 描述规范。它允许人类和计算机在不查看源码、文档或通过监控网络流量的情况下发现和理解服务。正确使用 OpenAPI ，可以让使用者在不需要或更少的理解服务实现逻辑情况下，更好更轻松的理解服务并与之交互。

完整的 OpenAPI 规范请看：OpenAPI Specification

上述说到 OpenAPI 是一个规范，而 Swagger 也是一个规范，是 OpenAPI 规范的前身。Swagger 规范已于 2015 年捐赠给 Linux 基金会后改名为 OpenAPI，并定义最新的规范为 OpenAPI 3.0。所以现在的 Swagger 3.0 就是 OpenAPI 3.0。

通常我们所说的 Swagger 是指由 SmartBear Software 开发维护的一套用于实现 OpenAPI 规范的工具组合名称。Swagger 工具包含开源、免费和商用工具的组合，可用于整个 API 生命周期的开发。

关于这两者区别的详细信息可查看：What Is the Difference Between Swagger and OpenAPI?

Swagger 官方：https://swagger.io/

一句话总结：OpenAPI 是一个规范，而 Swagger 是用于实现规范的工具组合。

SpringFox 是 Spring 社区维护的一个项目（非官方），帮助使用者将 Swagger 2 集成到 Spring 中。常常用于 Spring 中帮助开发者生成文档，并可以轻松的在 Spring Boot 中使用。

SpringFox 3.0 相关特性

• 支持 Spring 5，Webflux（仅请求映射支持，尚不支持功能端点）、Spring Integration
• 补充官方在 Spring Boot 的自动装配 ， 以后只需依赖一个
• 与2.0更好的规范兼容性
• 支持OpenApi 3.0.3
• 轻依赖 spring-plugin，swagger-core
• 现有的 Swagger 2 注解继续有效并丰富 OpenAPI 3.0 规范

Github: https://github.com/springfox/springfox

SpringDoc 也是 Spring 社区维护的一个项目（非官方），帮助使用者将 Swagger 3 集成到 Spring 中。

SpringDoc 支持 Swagger 页面 Oauth2 登录，相较于 SpringFox 而言，它的支撑时间更长，无疑是更好的选择。但是在国内发展较慢，很少看到太多有用的文档，百度出来的基本全是 Swagger 2 的内容，不过 官网文档 也给出了详细的使用说明。SpringDoc 使用了 Swagger 3（OpenAPI 3），但 Swagger 3 并未对 Swagger 2 的注解做兼容，不易迁移。

从 SpringFox 迁移到 SpringDoc

官网文档有介绍：Migrating from SpringFox

这里就不做过多介绍了。

以下将介绍使用 Springfox 来集成 Swagger 3 到 Spring Boot 中，并使用 Swagger 3 的注解。

关于使用 SpringDoc 来集成 Swagger 3（OpenAPI 3）的介绍请看我的另一篇文章：xxxx

1.

用于描述标签、文档信息、安全配置及外部文档，用在类上。

常用参数：

• ：描述文档信息，详情见以下的
• ：定义标签列表，详情见以下的
• ：目标服务器连接列表，详情见以下的
• ：API 的一些外部文档，详情见以下的

示例：

2.

用于说明文档信息，用在 中。

常用参数：

• ：应用标题
• ：应用描述
• ：联系信息，详情看
• ：许可信息，详情看
• ：版本

示例：

3.

对一个 operation 进行说明或定义的标签，用在类或方法上，也可以用在 中定义标签。

常用参数：

• ：名称
• ：描述

示例：

用在类上：

用在 中定义标签：

值得注意的是， 在使用 Springfox 整合时，配置在 Controller 上使用并没有生效，在 Swagger UI 中没有看到相关显示。 这似乎是个 BUG，相关 issues： @Tag annotation not work as expected on the Controller class. 。

目前还未修复，解决方法是使用 2.X 版本的注解替代： 。

这个问题在 Springdoc 中不存在，通过 Springdoc 来生成 API 文档时， 使用正常，在 Swagger UI 中正常显示。

4.

用于描述联系人信息，用在 中。

常用参数：

• ：唯一名称（个人/组织）
• ：指向联系人信息的 URL
• ：邮箱

示例：

5.

用于藐视许可证信息，用在 中。

常用参数：

• ：许可证名称
• ：指向许可证的 URL

示例：

6.

用于配置目标主机，用在 中。

常用参数：

• ：主机地址
• ：主机描述

示例：

7.

用于说明方法用途，用在方法上。

参数：

• ：方法概要，方法的一个简单介绍，建议 120 个字符内
• ：方法描述，一般是很长的内容
• ：是否隐藏

示例：

8.

用于说明方法参数，用在方法参数上。

参数：

• ：指定的参数名
• ：参数位置，可选 、、 或 ，默认为空，表示忽略
• ：参数描述
• ：是否必填，默认为

示例：

9.

用于说明一个响应信息，用在 中。

参数：

• ：HTTP 响应码
• ：描述

示例：

10.

用于说明一组响应信息，比如一个请求可能返回多种响应情况，比如成功信息（200），也有可能抛参数异常（400），用在方法上。

参数：

• ： 数组

示例参考以上的 。

11.

用于描述数据对象信息或数据对象属性，比如各种 POJO 类及属性，用在类或类属性上。

参数：

• ：属性名称
• ：属性描述
• ：是否必须
• ：字符最小长度
• ：字符最大长度

示例：

值得注意的是，当使用 Springfox 整合时， 配置在类上时在 Swagger UI 中并未生成其配置的信息，但是配置在类属性上却是正常的。配置在类上时可使用 来替代。

这个问题在使用 Springdoc 整合时不存在，在 Springdox 整合使用时， 配置在类和属性上均正常。

12.

用于隐藏资源、类或属性，用在类、方法或属性上。

示例：

一般常用的也就这几个注解，若想要了解更多的注解，请参阅 OpenAPI Specification 。

以下使用教程使用 Springfox 整合，可能对新注解支持不是特别好，有些注解添加了也不生效，因此以下配置中的代码并非全用到新注解。所以，我还是推荐使用 Springdoc 来整合生成文档。

关于使用 Springdoc 来整合 OpenAPI 3 生成文档的介绍，请看我的另一篇文章：Spring Boot 中使用 SpringDoc 整合 Swagger 3（OpenAPI 3）生成 API 文档

添加依赖

编辑 ，添加依赖：

添加 Swagger 配置类

1. 添加 Swagger 属性配置类，用于封装 Swagger 配置参数：

2. 添加 Swagger 配置类，添加注解 ：

使用 Swagger 3

1. 添加 Controller：

2. 添加 VO：

3. 编辑项目 ，添加以下参数：

4. 项目中如果使用了 Spring Security 的，要添加以下配置放行 Swagger UI 的相关资源：

5. 启动项目进行测试。

启动项目，浏览器访问：http://localhost:8080/swagger-ui/ （注意：Swagger 2.X 版本访问地址是 http://localhost:8080/swagger-ui.html，这和 3.0 不一样。），可看到 Swagger UI 界面：

主页面：

查看 GET 请求：

查看 POST 请求：

实体类描述：

至此，Spring Boot 中使用 SpringFox 整合 Swagger 3 的使用已完成。

示例代码已上传到 GitHub：spring-boot-springfox-swagger3 。

1. what-is-the-difference-between-swagger-and-openapi
2. Springfox Reference Documentation
3. Swagger3 注解使用（Open API 3）