Springfox、Springdoc和Swagger

Springfox、Swagger 和 Springdoc

Springfox、Swagger 和 Springdoc 是用于在 Spring Boot 项目中生成API文档的工具，但它们之间有显著的区别和演进关系：

1.Swagger

简介

• Swagger 是一个开源项目，旨在为 RESTful APIs 提供交互式文档。
• 最早由 SmartBear 开发，后来演进为 OpenAPI 规范 的前身。
• Swagger 的核心组件包括：
  • Swagger UI：提供交互式的 Web 界面，展示 API 端点并允许直接调用测试。
  • Swagger Editor：编写和查看 OpenAPI 描述文件的工具。
  • Swagger Codegen：基于 API 描述文件生成客户端和服务端代码。

与 Spring 的关系

Swagger 本身不依赖 Spring，但通过扩展工具（如 Springfox）使其在 Spring 框架中得到使用。

Swagger2是Swagger规范的一个实现

Swagger3是基于OpenAPI规范的新版本，它是Swagger规范的后续标准，
提供了更好的可扩展性和更丰富的功能。

Spring Boot从2.6.0版本开始不再原生支持Swagger2，因为Spring官方的更新导致了与Swagger2的不兼容。
开发者需要使用Springdoc OpenAPI库来替代Springfox，以在Spring Boot 2.6.0及以上版本中集成OpenAPI文档。
Springdoc OpenAPI提供了对OpenAPI 3.0规范的支持，并且与Spring Boot的新版本兼容。

2.Springfox

简介

• Springfox 是一个专门为 Spring Boot 集成 Swagger 的库。
• 核心功能：扫描 Spring 项目中的注解和配置，生成基于 Swagger 的 API 文档。
• 特点：
  • 支持 Spring MVC 和 Spring WebFlux。
  • 使用 @ApiOperation 和 @ApiModel 等注解来生成文档。
  • 支持 Swagger 2 和部分 OpenAPI 3 特性。

现状

• 停止活跃维护：Springfox 项目在 2021 年后维护频率大幅降低，社区对它的支持逐渐减少。3.0.x版本以后没有再更新
• 兼容性问题：
  • 与 Spring Boot 2.6.x 和更高版本存在兼容性问题，主要是因为 Springfox 使用的 RequestMappingHandlerMapping 被 Spring Framework 的 Web 模块改动影响。

何时使用

• 如果项目是基于 Spring Boot 2.5.x 或更早版本，并且已经使用了 Springfox，可以暂时保留。
• 对于新项目，不建议继续使用 Springfox。

3.Springdoc

简介

• Springdoc 是一个现代化工具，基于 OpenAPI 3 规范设计，替代 Springfox。
• 提供与 Spring Boot 的无缝集成：
  • 自动生成 OpenAPI 3 文档。
  • 提供嵌入式的 Swagger UI（无需单独配置）。
  • 兼容 Spring MVC 和 Spring WebFlux。

优点

• 强大兼容性：
  • 与 Spring Boot 2.x 和 3.x 完美兼容。
  • 支持 Spring Framework 的最新功能，例如响应式流和新注解模型。
• 零配置：
  • 大部分功能开箱即用，减少了复杂的注解和配置需求。
• 社区活跃：
  • 相比 Springfox，Springdoc 项目更活跃，持续发布新版本，解决社区反馈。

使用方式

1.添加 Maven 依赖：

<dependency>
 <groupId>org.springdoc</groupId>
 <artifactId>springdoc-openapi-ui</artifactId>
 <version>最新版本</version>
</dependency>

2.启用后，访问默认路径 http://localhost:8080/swagger-ui.html。

总结：它们的关系与选择

迁移建议：从 Springfox 到 Springdoc

如果你当前使用 Springfox，但需要升级 Spring Boot 或改进文档支持，可以迁移到 Springdoc：

1. 替换依赖：
   • 移除 springfox-swagger2 和 springfox-swagger-ui。
   • 添加 springdoc-openapi-ui。
2. 注解适配：
   • Springdoc 支持 OpenAPI 3 的注解，通常是标准的 JSR-303 和 Spring 注解。
   • 替换 @ApiOperation 为 @Operation，替换 @ApiModel 为标准注解。
3. 配置改动：
   • Springdoc 几乎不需要额外配置，大部分文档生成会自动完成。

结论：对于新项目，推荐使用 Springdoc；对于维护中的老项目，可以逐步迁移到 Springdoc，以便享受最新功能和更好的兼容性。

使用springboot2.6+版本和swagger2不兼容的解决方案

以下是一个springboot2.7.10集成swagger2和knife4j的例子

1、引入knife4j

 <dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-spring-boot-starter</artifactId>
     <version>3.0.3</version>
</dependency>

knife4j官方建议开发者不要使用

2、knife4j配置文件

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.co