完美集成 Swagger 到您的 SpringBoot 项目

Swagger 最初作为一套规范而问世，后来在 2015 年捐赠给Linux基金会后演变为 OpenAPI 规范（OAS）。这次转变标志着 API 文档编写和互操作性的一次进步，使其向 OpenAPI 3.0 过渡。在现今的行业讨论中，提到 Swagger 通常指的是 SmartBear Software 开发的一套用于实现 OpenAPI 规范的工具。这套工具包括开源、免费和商业工具的组合，支持 API 生命周期的各个开发阶段。

使用 Swagger 工具的核心在于采用设计优先的原则，把生成 API 文档视为开发过程的基石。开发者可以根据自己的偏好选择方法：一些人偏好使用 Swagger Editor 在线创建 API 文档，而另一些人则偏好编写代码时注释，让文档自动生成。这两种方法都为简化和优化开发过程提供了路径。

其中，Spring Boot 项目的集成已表现出良好的适应性，Springfox和Springdoc作为领先的开源库促进了这一整合。

`Springfox`与`Springdoc`深入探讨

Springfox：借鉴传统

Springfox 作为 Swagger 的 Java 实现，帮助生成兼容 Swagger 2.0 规范的 API 文档。它通过一系列注解为开发者提供了生成相应 API 文档的能力。此外，Springfox 还提供了可扩展接口，允许定制文档生成过程以满足特殊需求。尽管它因支持 Swagger 2 规范而被广泛使用，但更新速度缓慢和与新版本 Spring Boot 的兼容问题一直是人们关心的问题。

Springdoc：新兴前沿

与此同时，Springdoc 因其与 Spring Boot 的深度集成以及支持 OpenAPI 3.0 规范而脱颖而出。它涵盖了更广泛的Spring项目，包括 Spring WebMvc、Spring WebFlux、Spring Data Rest 和 Spring Security。以快速更新和生成 OpenAPI 3.0 规范文档而闻名，Springdoc 也为用户提供了自定义文档生成过程的能力，尽管目前支持的插件较少。

使用Springdoc-openapi发展文档

springdoc-openapi Java 库为 Spring Boot 应用中自动化生成 API 文档提供了创新解决方案。它通过审查应用的 Spring 配置、类结构和注释来推断 API 语义，产生格式化的 JSON/YAML 和 HTML 文档。

快速开始 Springdoc

安装依赖: 确认在项目的 POM 文件中加入最新版的springdoc-openapi-ui依赖。
启用Swagger: 在application.yml文件中修改配置以根据需要启用或禁用 Swagger 3。
配置SwaggerController: 实现一个 Swagger3Config 类来配置 API 分组，并为操作添加自定义参数或头部。
注释实体类: 对你的实体类使用 Swagger 的@Schema注释，以便准确地进行文档编写。
控制器注释: 通过为控制器方法添加 Swagger 的@Operation和@Parameter注释来精确定义 API。

访问 Swagger UI

通过访问http://server:port/context-path/swagger-ui.html来查看生成的 Swagger 文档。

其他方式

虽然springdoc-openapi为 API 文档提供了无与伦比的支持，但将其与 Apifox 整合为分享和同步 API 细节提供了一个吸引人的途径。Apifox 提供了一个全面的平台，支持 API 设计、文档、测试和协作功能，能够自动解析代码注释并从 Javadoc、KDoc 和 ScalaDoc 生成 API 文档。通过使用 IntelliJ IDEA 的 Apifox Helper 插件，开发人员可以在不离开 IDE 的情况下与 Apifox 项目同步他们的文档。此外，Apifox 通过其直观的UI丰富了 API 管理体验，支持从 IDEA 直接启动内部测试和导出文档。

对于希望提升 API 文档和协作工作流的开发人员，采用 Apifox 与 Springdoc-openapi 可能成为改变游戏规则的策略。