Spring Boot中使用Swagger3.0.0版本构建RESTful APIs

@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)