OpenAPI 2.0（即Swagger 2.0）与OpenAPI 3.0在规范架构、数据模型和功能特性上存在显著差异，升级时需注意依赖、注解和配置的全面调整。

一、OpenAPI 2.0 与 OpenAPI 3.0 核心区别

二、从 OpenAPI 2.0 升级至 3.0 的关键注意事项

1. 依赖与库的更换

升级的核心是替换底层实现库。对于Spring Boot项目：

• 移除旧依赖：需移除 springfox-swagger2、springfox-swagger-ui、swagger-annotations、swagger-models 等。
• 添加新依赖：引入 springdoc-openapi-starter-webmvc-ui（用于Spring MVC）或相应WebFlux依赖，以及 knife4j-openapi3-jakarta-spring-boot-starter（如果使用Knife4j增强UI）。

  <!-- Maven 示例：Spring Boot 3 + OpenAPI 3.0 + Knife4j -->
  <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.5.0</version>
  </dependency>
  <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
      <version>4.4.0</version>
  </dependency>
  

• Jakarta EE 兼容性：Spring Boot 3 默认使用 Jakarta EE 9+，将 javax.servlet 包替换为 jakarta.servlet。所有相关依赖（如 knife4j）必须使用 Jakarta 兼容版本。

2. 注解的迁移与重写

代码中的注解需要批量替换，这是升级的主要工作量所在。

示例：控制器升级对比

// OpenAPI 2.0 风格 (SpringFox)
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import javax.servlet.http.HttpServletRequest;

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理接口") // 旧注解
public class UserController {

    @GetMapping("/{id}")
    @ApiOperation("根据ID查询用户") // 旧注解
    public User getUser(@PathVariable @ApiParam("用户ID") Long id) { // 旧注解
        // ... 业务逻辑
    }
}

// OpenAPI 3.0 风格 (SpringDoc)
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.servlet.http.HttpServletRequest; // 注意包名变化

@RestController
@RequestMapping("/user")
@Tag(name = "用户管理接口") // 新注解
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "根据ID查询用户") // 新注解
    public User getUser(@PathVariable @Parameter(description = "用户ID") Long id) { // 新注解
        // ... 业务逻辑
    }
}

3. 配置文件的调整

• 配置属性前缀变化：SpringFox的配置前缀是 springfox 或 swagger，而SpringDoc的配置前缀统一为 springdoc。

  # SpringDoc 配置示例 (application.yml)
  springdoc:
    api-docs:
      path: /v3/api-docs # OpenAPI JSON 端点
    swagger-ui:
      path: /swagger-ui.html # Swagger UI 访问路径
      operations-sorter: method # 接口排序方式
    default-consumes-media-type: application/json
    default-produces-media-type: application/json
  

• 自定义配置类：原有的 @EnableSwagger2 或 Docket Bean 配置方式不再适用。SpringDoc 通常通过属性文件配置，复杂定制可通过实现 OpenApiCustomiser 接口或定义 GroupedOpenApi Bean 来完成。

4. 访问路径与UI变化

• JSON描述文件路径：默认从 /v2/api-docs 变为 /v3/api-docs。
• UI访问路径：Swagger UI 默认路径可能仍是 /swagger-ui.html，但内部解析的规范版本已变。如果集成了Knife4j，其增强UI的访问路径通常是 /doc.html。
• UI依赖：springdoc-openapi 已内置 Swagger UI，无需单独引入 swagger-ui 依赖。

5. 其他潜在问题

• 枚举处理：OpenAPI 3.0 对枚举类型的生成可能更严格，需检查 @Schema 注解在枚举字段上的行为是否符合预期。
• 泛型与复杂嵌套模型：升级后需验证复杂泛型、继承关系的模型在生成的Schema中是否正确呈现。
• 安全配置迁移：如果原项目使用了Swagger的 securitySchemes（如API Key、OAuth2），需按OpenAPI 3.0格式在 components 中重新定义。
• 全局统一响应/参数：原先通过 Docket 的 globalOperationParameters 或 globalResponseMessage 添加的全局元素，需改用 OpenApiCustomiser 或 GroupedOpenApi Bean 进行编程式配置。

升级建议流程：1) 在独立分支进行；2) 先更新依赖并确保编译通过；3) 批量替换注解（可利用IDE的查找替换功能）；4) 调整配置；5) 启动应用，访问 /v3/api-docs 验证JSON结构，再访问UI页面测试接口文档的完整性和正确性；6) 重点关注之前使用了复杂Swagger注解或配置的接口。

参考来源

• Spring Boot 3 + JDK 21 项目中从 Swagger 2 升级到 OpenAPI 3.0（Knife4j）的完整实践指南——以苍穹外卖项目为例
• Springboot 2.7 集成 Swagger 增强版接口框架 Knife4j 4.3 + springdoc OpenApi 3.0
• JeecgBoot 框架升级至 Spring Boot3 的实战步骤_jeecgboot升级到最新版
• 深入理解drf-yasg项目的OpenAPI规范实现
• JeecgBoot 框架升级至 Spring Boot3 的实战步骤_jeecgboot升级到最新版
• 11、使用 Docker 部署微服务与添加 OpenAPI 接口文档