@[toc]

一、项目描述

为了练习 Spring Boot 中使用 Swagger3.0.0 版本生成可视化的 swagger 接口文档本项目涉及的版本

• Spring 版本：5.3.22

• SpringBoot 版本：2.7.3

• Swagger 版本：3.0.0

二、简介

一般我们在对接前后端的时候，都需要提供相应的接口文档。对于后端来说，编写接口文档即费时费力，还会经常因为没有及时更新，导致前端对接时出现实际接口与文档不一致。而且手写接口文档还容易出错，而 swagger 很好的解决了这个痛点。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。可用于：1.接口的文档在线自动生成、2.功能测试。

三、Swagger2.X 和 Swagger3.0.0 的对比

1）SpringFox 2.x 发布

此版本的亮点：

• 号称时最流行的 API 框架

• 接口文档在线生成，避免同步的麻烦

• 可以支持在线对接口执行测试

• 支持多语言

SpringBoot 项目整合 swagger2 需要用到两个依赖：springfox-swagger2 和 springfox-swagger-ui，用于自动生成 swagger 文档。

springfox-swagger2：这个组件的功能用于帮助我们自动生成描述 API 的 json 文件 springfox-swagger-ui：就是将描述 API 的 json 文件解析出来，用一种更友好的方式呈现出来。

2）SpringFox 3.0.0 发布

此版本的亮点：

• Spring5，Webflux 支持（仅支持请求映射，尚不支持功能端点）。

• Spring Integration 支持。

• SpringBoot 支持 springfox Boot starter 依赖性（零配置、自动配置支持）。

• 支持 OpenApi 3.0.3。

• 零依赖。几乎只需要 spring-plugin，swagger-core ，现有的 swagger2 注释将继续工作并丰富 openapi3.0 规范。

兼容性说明：

• 需要 Java 8

• 需要 Spring5.x（未在早期版本中测试）

• 需要 SpringBoot 2.2+（未在早期版本中测试）

3）swagger3.0 与 2.xx 配置差异：

• 应用主类添加注解 @EnableOpenApi (swagger2 是 @EnableSwagger2)

• swagger 配置类 SwaggerProperties.class，与 swagger2.xx 版本有差异，具体看下文

• 自定义一个配置类 SwaggerConfiguration.class,看下文

• 访问地址：http://localhost:8080/swagger-ui/index.html(swagger2.xx 版本访问的地址为 http://localhost:8080/swagger-ui.html)