什么是 OpenAPI？

OpenAPI 文件，也称为 OpenAPI 文档或 OpenAPI 规范，使开发人员能够描述 API。本规范还描述了如何使用此 API，包括可用的端点、操作参数、身份验证方法和其他信息。这些规范以 YAML 或 JSON 编写，JSON 模式用于描述 API 内的数据格式。

OpenAPI 既是文档，也是 API 使用者和生产者之间的合同，从业务层面约定 API 应该具备的能力，但不具备法律约束力。它本质上充当“一个可信信息源”，以标准化格式提供相关说明。

这种标准化简化了 API 的使用和集成。它使人类和计算机都能理解给定 API 的功能和结构，而无需访问源代码或是钻研 API 的内部工作原理。它还允许开发人员使用 API，无论 API 是用什么语言编写的。

OpenAPI 可自动生成交互式、最新的文档，减少部分重复性文档工作，并有助于确保文档保持最新状态。OpenAPI 还支持为客户端 SDK 生成代码，并根据规范自动生成其他样板代码，从而减少人为错误，进一步减轻开发人员的工作量。

使用 OpenAPI 规范的工具（包括 SwaggerUI）可以在交互式界面中呈现 API 规范。该界面不仅有助于直观展示规范，还能直接从浏览器或网络服务发起真实 API 调用，用于测试和验证。

通过标准化 REST API 的描述方式，OpenAPI 有助于提升互操作性与配套工具能力，支撑 API 全生命周期的各项操作。一份完善且持续维护的规范可作为落地全面 API 策略的基础工具，支撑集成、协作、差错防控与精细化 API 管理。

完整的规范可在 GitHub 上查阅。

作为事实上的行业标准，OpenAPI 为 API 开发提供一份安全、自动化且被行业广泛认可的文档。

OpenAPI 最初由开发人员 Tony Tam 创建，并于 2011 年以 Swagger 为名首次发布。当时，API 规范大多是静态文档，更新流程繁琐，文档内容很容易过时。Swagger 规范在 API 开发中加入多项创新，其中包含“试用”按钮，可实时在线测试 API 调用。

Swagger 将文档作为产品设计的核心。它使开发人员能够在源代码中添加类似便签的注释内容。Swagger 能够读取这类注释并自动更新文档，免去繁琐重复的手动更新，保障文档持续最新。Swagger 还推出基于机器可读 JSON 的 API 描述格式，实现编程语言无关，无论后端采用何种开发语言，Swagger 都能输出通用 JSON 文件。

Swagger 在 2015 年被 SmartBear Software 收购，之后更名为 OpenAPI，并交由 Linux 基金会旗下全新的 OpenAPI Initiative (OAI) 托管。当前版本为 OpenAPI 3.1。

OpenAPI 规范是一份标准化、可被人类与机器读取的文档，用来定义 API 的结构与语法。所有 OpenAPI 文档都包含固定组件，遵循统一基础架构，部分规范会附带更多补充信息。一份规范最少需要包含 openAPI 和info 字段，以及至少一个 path 、component 或webhook 字段。¹

openAPI：注明文档所使用的 OpenAPI 版本，例如“3.1.1”。

info：包含常规 API 元数据，例如 API 标题和版本号、API 描述、服务条款以及联系信息。

servers：可供访问 API 的基础 URL 列表，其中可能包含预发布环境与生产环境。此列表包含适配不同环境主机的变量。

paths：描述路径及配套 HTTP 方法，例如 GET、PUT、POST，同时写明每条路径对应的参数、请求体与返回内容。

components：罗列各类可复用对象，例如数据模式、参数、返回内容、请求头与安全定义。在整个规范文档中都可以引用这些对象。组件的引用方式十分简便，通过 $ref 即可实现。该设计思路能够最大限度精简 API 架构。

security：写明 API 所采用的安全方案与鉴权机制，例如 OAuth 或 API keys。它支持全局配置安全方案，也可以按单个接口单独配置。

tags：用于归类接口操作的顶层标签清单。合理使用标签可以提升文档可读性，例如“用户”或“订单”。

external documentation：指向 API 配套指南、入门文档以及其他外部资料的链接

webhook：描述 API 所接收的各类入站请求。

OpenAPI 为 API 开发人员和使用者提供了单一可信信息源，并提供了可为 API 项目增加价值和效率的功能。

OpenAPI 最初创建时非常注重 REST API 的文档，并且这一重点至今仍然是其核心。文档是标准化、交互式且实时更新的，依托单一可信信息源形成规范约定。

有各类工具可以读取 OpenAPI 文档并导出代码。Swagger Codegen 就是其中之一，它可以读取根据 OpenAPI 规范编写的文档。随后，Swagger Codegen 可以生成 API 客户端代码、软件开发工具包 (SDK)、服务端桩代码以及附带最新文档的可读网页。

OpenAPI 最具创新性的功能之一仍是“试用”按钮，可直接在浏览器中完成实时测试与校验。Swagger 用户界面是一款免费开源工具，提供可视化界面，开发人员可发送真实请求，核验接口返回是否符合预期。借助该工具，能够快速核验请求是否正常运行。

OpenAPI 通常和集成平台即服务 (iPaaS) 搭配使用。

iPaaS 平台依托 OpenAPI 规范识别并打通 IT 生态系统内的各类应用程序。当应用程序对外提供描述自身 API 的 OpenAPI 规范时，iPaaS 平台可借助这些信息自动识别端点、鉴权方式与数据结构。这种战略能够加快集成搭建效率，例如打通电商平台与财务软件。

OpenAPI 还支持前端与后端开发人员同步开展开发工作。这种并行开发模式，可避免前端团队被动等待后端团队完成数据库部署上线的常见问题。依托 OpenAPI 合约，前端团队可搭建模拟 API 服务器，其运行效果与真实服务器一致，便于在后端开发收尾前开展并优化测试工作。

API 治理是规范组织开发和使用 API 的标准、政策与执行准则，能够有效保障 API 平稳、统一运行，杜绝不必要的重复操作。由于 OpenAPI 可作为开发人员之间的协作契约，因此可在项目初期就纳入治理规范与安全机制。

以 API 网关为例，其主要负责流量路由、运行监控、速率限制等各类工作。API 网关通常可适配 OpenAPI 规范，严格执行规范中设定的流量限制及各类安全防护措施。

安全规则的执行也遵循同样的逻辑。OpenAPI 规范支持开发人员定义安全要求（例如 OAuth 2.0、API 密钥的使用规则），这些要求可在下游环节落地执行（通常由网关执行）。在 API 合约中明确安全规范，可有效避免开发人员使用不兼容的安全方案。

OpenAPI 可以从多个维度强化 API 管理工作，也就是 API 创建、发布及连接管理的可扩展流程。举例来说，OpenAPI 规范具备机器可读、标准化的特性，目录和门户软件可对其自动建立索引。这套标准化特性让组织内部的 API 更便于检索和理解。良好的可发现性能够有效避免各团队无意识开发重复 API 的问题。

OpenAPI 通过明确且可落地的组织标准，助力 API 管理与治理工作保持统一规范。团队可直接在规范内或配套文档中定义各类要求，包括版本规则、错误响应格式、命名规范等内容。这些规范要求以标准化形式留存，新增 API 时系统可自动完成合规校验。该校验机制减少了人工审核的依赖，确保组织业务规模扩张后，各类 API 仍能保持规范统一。