OpenAPI 规范

OpenAPI 规范(OpenAPI Specification,OAS)是一种用于描述 HTTP 风格 API 的标准化、机器可读的接口定义格式。它以 YAML 或 JSON 编写,完整刻画一个 API 的端点、请求参数、响应结构与安全机制,成为前后端与工具链之间的通用契约。

概述

OpenAPI 的前身是 Swagger 规范,由 Tony Tam 于 2011 年发起。2015 年,SmartBear 将其捐赠给 Linux 基金会下的 OpenAPI 计划,更名为 OpenAPI 规范并推动标准化。它不是某个具体软件,而是一份行业约定的描述格式,围绕它形成了庞大的工具生态。

核心特点

• 语言无关:用中立的文本格式描述接口,不绑定任何编程语言或框架。
• 结构完整:可声明路径、HTTP 方法、请求体、参数、状态码、数据模型(Schema)与认证方式。
• 可自动化:据此可自动生成交互式文档、多语言客户端 SDK、服务端桩代码,以及契约测试与 Mock 服务。
• 版本演进:从 2.0(即原 Swagger)到 3.x,持续增强对复杂数据模型、回调、链接等特性的表达能力。

应用场景

团队在设计 API 时,常先用 OpenAPI 写出契约,再据此并行开发前后端并生成文档,实现契约优先(design-first)的协作模式。它也广泛用于生成对外的开发者文档门户、驱动网关的路由与校验配置、以及在持续集成中做接口的兼容性检查。众多云平台与 API 网关都原生支持导入 OpenAPI 定义。

常见问题

问:OpenAPI 和 Swagger 是一回事吗?答:Swagger 现指围绕该规范的一套工具(如 Swagger UI、Editor);而规范本身自 3.0 起正式称为 OpenAPI 规范,两者一脉相承但概念上已区分。

问:OpenAPI 能描述 GraphQL 或 gRPC 吗?答:不能,它专为 REST 风格的 HTTP API 设计;GraphQL 和 gRPC 各有自己的 Schema 与 IDL 描述方式。