Swagger与OpenAPI对比解析

## Swagger与OpenAPI对比：实用集成指南 在Java生态系统中，API文档的生成离不开Swagger和OpenAPI。OpenAPI是API描述的标准规范，而Swagger则是一套实现该规范的工具集。本文旨在阐明二者关系，并提供在Java项目中集成API文档的实用指南，重点介绍如何通过springdoc-openapi库自动生成符合OpenAPI规范的文档，并利用Swagger UI进行可视化展示，从而显著提升开发效率。本文还将深入探讨OpenAPI作为API描述未来的意义，以及Swagger作为其实现工具箱的角色，同时解析集成过程中可能遇到的常见问题及最佳实践，助力开发者在微服务架构下高效聚合和管理多个Java服务的API文档。

OpenAPI是API描述标准，Swagger是实现工具集；在Java中通过springdoc-openapi集成，自动生成文档并用Swagger UI展示，提升开发效率。

在Java生态中，谈及API文档生成，Swagger和OpenAPI是两个绕不开的名字，但它们之间的关系，很多时候会让人有些混淆。简单来说，OpenAPI Specification (OAS) 是一套定义和描述RESTful API的语言无关的标准规范，它就像是API的蓝图。而Swagger则是一个工具集，其中包含了Swagger UI（用于可视化API文档）、Swagger Editor（用于编辑OAS文件）和Swagger Codegen（用于生成客户端和服务端代码）等，这些工具的核心目的，就是帮助我们更好地创建、维护和使用遵循OpenAPI规范的API。因此，与其说是“对比”，不如理解为Swagger是实现和利用OpenAPI规范的强大“手艺”。在Java集成实践中，我们通常会使用一些库（如springdoc-openapi或历史上的springfox-swagger2）来自动根据代码生成符合OpenAPI规范的文档，并通过Swagger UI将其展现出来。

解决方案

在Java项目中集成API文档生成功能，尤其是基于Spring Boot的微服务，现在主流且推荐的做法是采用springdoc-openapi库。它能够无缝地与Spring Boot 2.x/3.x、Spring WebFlux、Kotlin等技术栈结合，自动扫描你的控制器（Controller）代码，根据注解和反射机制生成符合OpenAPI 3.0.x规范的JSON/YAML文档，并提供一个美观的Swagger UI界面供开发者和测试人员交互。

核心集成步骤通常包括：

1. 添加Maven/Gradle依赖： 在pom.xml（Maven）或build.gradle（Gradle）中引入springdoc-openapi-ui依赖。这个依赖通常会包含springdoc-openapi-webmvc-core（或webflux-core）和swagger-ui。

   <!-- Maven 示例 -->
   <dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-ui</artifactId>
       <version>1.7.0</version> <!-- 根据你的Spring Boot版本选择兼容的版本 -->
   </dependency>

2. 基本配置（可选但推荐）： 在application.properties或application.yml中进行一些基本配置，比如修改Swagger UI的路径、禁用某些API等。例如：

   # application.yml
   springdoc:
     swagger-ui:
       path: /swagger-ui.html # 默认就是这个，但你可以改
       tags-sorter: alpha # 标签按字母排序
       operations-sorter: method # 操作按HTTP方法排序
     api-docs:
       path: /v3/api-docs # 默认路径，可以修改

3. 使用OpenAPI注解增强文档： 虽然springdoc-openapi能自动生成大部分内容，但为了生成更详尽、更友好的文档，我们通常会结合OpenAPI注解。

   • @Tag(name = "用户管理", description = "用户相关的CRUD操作")：用于控制器类或方法，定义API的标签和描述，在Swagger UI中会作为分组。
   • @Operation(summary = "获取所有用户列表", description = "分页查询所有注册用户的信息")：用于API方法，提供更具体的摘要和描述。
   • @Parameter(description = "用户ID", required = true, example = "123")：用于方法参数，描述参数的用途、是否必需、示例值等。
   • @ApiResponse(responseCode = "200", description = "成功获取用户列表", content = @Content(mediaType = "application/json", schema = @Schema(implementation = UserListResponse.class)))：描述API的响应，包括状态码、描述和响应体结构。
   • @Schema(description = "用户数据模型")：用于DTO（数据传输对象）类或字段，描述数据模型的结构。

集成后的效果：

启动Spring Boot应用后，访问http://localhost:8080/swagger-ui.html（或你配置的路径），就能看到一个交互式的API文档界面。这个界面不仅能清晰地展示所有API的路径、参数、响应模型，还能直接发送请求进行测试，极大地提高了开发和联调效率。

为什么OpenAPI是API描述的未来，而Swagger更像是其实现工具箱？

在我看来，这种区分是理解现代API开发的关键。OpenAPI Specification的出现，解决了API描述的标准化问题。想象一下，如果每个团队、每个项目都用自己的方式来描述API，那协作和工具链的构建会变得异常困难。OpenAPI提供了一套语言无关、机器可读的契约，它详细定义了API的路径、操作、参数、响应、安全方案等所有细节。这意味着，无论你用Java、Python还是Node.js开发API，只要遵循OpenAPI规范，你的API就能被所有支持OpenAPI的工具理解和处理。

而Swagger，它最初是一个工具集，包含了最早的API描述格式Swagger Specification（后来捐献给Linux基金会，演变为OpenAPI Specification）以及围绕这个规范构建的各种工具。当人们谈论“Swagger”时，往往指的是Swagger UI这个最直观的工具，因为它提供了API的可视化界面和测试功能。但实际上，Swagger家族还有Swagger Editor用来编写OAS文件，以及Swagger Codegen用来根据OAS文件生成客户端SDK或服务器端桩代码。

所以，OpenAPI是“是什么”，它定义了API的契约和结构；Swagger是“怎么做”，它提供了一系列工具来帮助我们创建、使用和可视化符合OpenAPI规范的API。这种分工明确，使得API生态能够更加健壮和开放。我们现在使用的springdoc-openapi，其核心就是根据Java代码生成符合OpenAPI 3.0.x规范的JSON/YAML文件，然后用Swagger UI来渲染它。

在Spring Boot项目中，集成springdoc-openapi有哪些常见“坑”和最佳实践？

集成springdoc-openapi通常很顺利，但偶尔也会遇到一些让人挠头的问题，以及一些可以提升体验的最佳实践。

常见“坑”：

1. 版本兼容性问题： springdoc-openapi的版本需要与你的Spring Boot版本以及Java版本兼容。例如，Spring Boot 3.x需要springdoc-openapi 2.x及以上版本，并且要求Java 17。如果你不小心混用了不兼容的版本，可能会导致启动失败、Swagger UI无法加载或API文档生成不完整。解决办法是仔细查阅springdoc-openapi的官方文档，确认与你的项目环境匹配的版本。
2. 默认路径冲突： 如果你的应用中已经存在/swagger-ui.html或/v3/api-docs等路径，可能会导致冲突。可以通过配置springdoc.swagger-ui.path和springdoc.api-docs.path来修改默认路径。
3. 安全配置： 当你的Spring Boot项目启用了Spring Security时，Swagger UI的访问可能会被拦截。你需要在Spring Security的配置中，允许对/swagger-ui.html、/v3/api-docs/**等路径的匿名访问。一个常见的做法是添加如下配置：

   @Configuration
   @EnableWebSecurity
   public class SecurityConfig {
       @Bean
       public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
           http
               // ... 其他安全配置
               .authorizeHttpRequests(authorize -> authorize
                   .requestMatchers("/swagger-ui.html", "/swagger-ui/**", "/v3/api-docs/**").permitAll()
                   .anyRequest().authenticated()
               );
           return http.build();
       }
   }

4. 复杂类型或泛型处理不当： 对于一些复杂的响应类型，比如ResponseEntity>，springdoc-openapi可能无法完美推断出MyObject的Schema。这时就需要手动使用@ApiResponse和@Content(schema = @Schema(implementation = MyObject.class))来明确指定响应类型。泛型尤其麻烦，有时候需要创建包装类来辅助。
5. 自定义注解不被识别： 如果你使用了自定义的Spring注解来简化Controller代码，springdoc-openapi可能无法解析其内部的@RequestMapping等信息。你需要确保你的自定义注解被正确地元注解（meta-annotated）了Spring框架的注解，或者为springdoc-openapi提供自定义的OperationCustomizer。

最佳实践：

1. 充分利用OpenAPI注解： 尽管springdoc-openapi能自动生成基础文档，但为了提供高质量、易于理解的API文档，务必花时间使用@Tag, @Operation, @Parameter, @ApiResponse, @Schema等注解来丰富描述、示例和数据模型。这不仅方便了消费者，也强制开发者思考API的设计。
2. 维护清晰的DTO： 保持你的请求体和响应体（DTOs）结构清晰、字段命名规范，并使用@Schema注解提供字段描述和示例。这对于生成准确且有用的文档至关重要。
3. 配置API分组： 对于大型应用，通过springdoc.group-configs配置多个API分组，可以按业务模块、版本等维度组织API文档，让用户更容易找到所需内容。例如：

   springdoc:
     group-configs:
       - group: users
         paths-to-match: /api/v1/users/**
         display-name: 用户服务V1
       - group: products
         paths-to-match: /api/v1/products/**
         display-name: 产品服务V1

4. 持续集成/部署中的文档生成： 将OpenAPI文档的生成作为CI/CD流程的一部分。可以在构建阶段生成JSON/YAML格式的API文档文件，并将其存储在版本控制系统或共享位置。这样，即使不启动应用，也能获取最新的API契约。
5. 结合Postman/Insomnia等工具： 许多API客户端工具支持导入OpenAPI规范文件。在springdoc-openapi生成文档后，你可以下载/v3/api-docs生成的JSON文件，导入到这些工具中，快速生成请求集合，进一步提升开发效率。

微服务架构下，如何高效聚合和管理多个Java服务的API文档？

在微服务架构中，每个服务都有自己的API文档，这很自然。但对于API消费者（前端、其他服务或第三方开发者）来说，他们可能需要一个统一的入口来查看所有服务的API文档，而不是逐个访问。这就引出了API文档聚合的需求。

常见的聚合和管理策略：

1. API Gateway聚合： 如果你的微服务架构中使用了API Gateway（如Spring Cloud Gateway、Zuul、Kong、Tyk等），这通常是聚合API文档最自然的方式。

   • 原理： API Gateway作为所有外部请求的唯一入口，可以配置路由规则将请求转发到不同的后端服务。我们可以让API Gateway也暴露一个聚合的Swagger UI。
   • 实现方式（以Spring Cloud Gateway为例）：
     • 每个微服务都独立集成springdoc-openapi，并暴露自己的/v3/api-docs端点。
     • 在API Gateway服务中，引入springdoc-openapi-webflux-ui依赖（因为Gateway通常基于WebFlux）。
     • 配置Gateway，让它能够发现并代理各个微服务的/v3/api-docs端点。springdoc-openapi提供了一个springdoc-openapi-webflux-ui模块，结合服务发现（如Eureka、Nacos），可以自动聚合所有服务的API文档。你需要在Gateway的配置中添加springdoc.swagger-ui.urls或使用springdoc.api-docs.enabled=true并配合服务发现机制。
     • 访问Gateway的/swagger-ui.html，你就能看到一个下拉菜单，列出所有微服务的API文档。

   优势： 统一入口，无需额外部署，与API路由紧密结合。 挑战： 配置相对复杂，需要处理服务发现和路由。

2. 独立文档门户（Documentation Portal）： 部署一个独立的Web应用作为API文档门户。

   • 原理： 这个门户应用不直接提供API功能，只负责收集并展示所有微服务的API文档。
   • 实现方式：
     • 每个微服务依然独立生成自己的OpenAPI JSON/YAML文件（可以在CI/CD阶段生成并上传到共享存储）。
     • 文档门户应用可以定期从各个微服务的/v3/api-docs端点拉取最新的OpenAPI文件，或者从共享存储读取。
     • 门户应用可以使用Swagger UI的JavaScript库手动加载和渲染这些OpenAPI文件，或者使用其他专门的文档生成工具（如Redoc、Slate）来展示。 优势： 高度解耦，灵活定制UI，不依赖API Gateway。 挑战： 需要额外部署和维护一个应用，可能需要手动管理OpenAPI文件的更新机制。

3. CI/CD管道集成： 将OpenAPI文档的生成和收集集成到CI/CD管道中。

   • 原理： 在每个微服务构建完成后，自动生成其OpenAPI JSON/YAML文件，并将其发布到中央存储库（如Artifactory、S3桶，或一个Git仓库）。
   • 实现方式： 可以编写脚本，在构建阶段运行springdoc-openapi-maven-plugin或springdoc-openapi-gradle-plugin来生成文件，然后上传。一个中央的文档门户可以从这个存储库中读取所有文件并展示。 优势： 确保文档与代码版本同步，自动化程度高，易于审计。 挑战： 需要完善的CI/CD流程和存储策略。

选择哪种策略取决于你的团队规模、技术栈、现有基础设施以及对文档实时性、可维护性的要求。在我参与的项目中，对于有API Gateway的场景，Gateway聚合是最常见的选择，因为它减少了额外的部署和维护成本。而对于更复杂的、需要对外提供统一开发者体验的场景，独立文档门户则能提供更大的灵活性和定制空间。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~