OpenAPI vs Swagger：理解两者的区别

在 API 开发领域，"OpenAPI"和"Swagger"这两个术语经常被混淆使用。理解它们之间的区别对于正确使用 API 开发工具至关重要。

历史背景

Swagger（2011-2015）

• 由 Wordnik 的 Tony Tam 创建
• 最初是一个开源项目
• 包含规范和工具（Swagger UI、Swagger Editor）
• 成为 API 描述的事实标准

演变（2015-至今）

• 2015 年：SmartBear 收购 Swagger
• 2015 年：Swagger 规范捐赠给 Linux 基金会
• 2016 年：成立 OpenAPI Initiative（OAI）
• 2017 年：发布 OpenAPI 规范 3.0
• 现在：Swagger 作为工具品牌继续存在

核心区别

OpenAPI 规范（OAS）

是什么：一个开放的、供应商中立的 API 描述格式标准

管理机构：

• OpenAPI Initiative（Linux 基金会）
• 成员包括：Google、Microsoft、IBM、PayPal 等

技术本质：

• YAML 或 JSON 格式的文件
• 定义 API 的结构、端点、参数、响应等
• 当前版本：3.1.0

作用：

• 作为 API 契约的单一事实来源
• 机器可读的 API 文档
• 代码生成的基础

Swagger

是什么：一系列帮助使用 OpenAPI 规范的工具

所有者：SmartBear Software

主要产品：

1. Swagger Editor：在线编辑 OpenAPI 文件
2. Swagger UI：将 OpenAPI 文件渲染为交互式文档
3. Swagger Codegen：从 OpenAPI 文件生成客户端/服务器代码
4. SwaggerHub：商业协作平台

作用：

• 创建、编辑 OpenAPI 文件
• 可视化 API 文档
• 生成代码和测试

类比理解

建筑行业类比

• OpenAPI 规范 = 建筑设计规范（ISO 标准）

  • 规定如何描述建筑图纸
  • 供应商中立的国际标准

• Swagger 工具 = AutoCAD（具体软件）

  • 帮助绘制建筑图纸
  • 符合设计规范的软件工具

编程语言类比

• OpenAPI 规范 = HTML 规范（W3C 标准）

  • 定义标记语言的语法和语义

• Swagger 工具 = WebStorm / VS Code

  • 帮助编写 HTML 的工具

如何协同工作

1开发者
2  ↓
3使用 Swagger Editor（工具）
4  ↓
5编写/编辑 openapi.yaml（遵循 OpenAPI 规范）
6  ↓
7使用 Swagger UI（工具）查看文档
8使用 Swagger Codegen（工具）生成代码
9  ↓
10API 网关读取 OpenAPI 文件自动配置路由

版本对应关系

注意：Swagger 2.0 就是 OpenAPI 2.0，只是在 3.0 版本后更名。

正确使用

应该说

• "我们的 API 遵循 OpenAPI 3.0 规范"
• "使用 Swagger UI 查看 API 文档"
• "用 Swagger Codegen 生成客户端 SDK"
• "导入 OpenAPI 文件到 API 网关"

避免说

• "我们使用 Swagger 规范"（应为 OpenAPI 规范）
• "这是 Swagger 文件"（更准确的说是 OpenAPI 文件）
• "OpenAPI UI"（应为 Swagger UI 或其他工具）

生态系统

OpenAPI 工具生态（不仅限于 Swagger）

• 编辑器：VS Code + OpenAPI 插件、Insomnia
• 文档：ReDoc、Stoplight Elements
• 测试：Postman、Insomnia
• 代码生成：OpenAPI Generator（社区版）
• 网关：Apache APISIX、Kong、Tyk

选择建议

• 文档生成：Swagger UI 或 ReDoc
• 代码生成：OpenAPI Generator（功能更丰富）
• 团队协作：SwaggerHub 或 Stoplight
• CI/CD：开源 CLI 工具

对 API 管理的意义

现代 API 网关可以直接消费 OpenAPI 规范：

1. 自动路由配置：根据 OpenAPI 文件自动生成路由
2. 认证策略：读取安全定义自动配置认证
3. 请求验证：根据 schema 验证请求参数
4. 文档发布：自动生成开发者门户文档

1# 示例：Apache APISIX 导入 OpenAPI
2apisix.yaml:
3  plugins:
4    - openapi:
5        file: "petstore.yaml"
6        auto_generate_routes: true

总结

记住：OpenAPI 是标准，Swagger 是工具。两者相辅相成，共同推动 API 开发的标准化和自动化。