OpenAPI 是 REST API 的标准机器可读描述,涵盖端点、参数、架构和错误,可据此生成类型化客户端库、文档和 API 工具集合。
OpenAPI 文档以 YAML 或 JSON 编写,对 REST API 的描述精确到软件可以直接据此工作的程度:服务器、每个路径和操作、参数和请求正文、成功及每种错误的响应架构,以及身份验证方案。该规范源自 Swagger,由 OpenAPI Initiative 维护;3.1 版使其架构与 JSON Schema 保持一致。
凭借这一个文件,工具就能生成 TypeScript、Python、Java 等多种语言的类型化客户端,把 API 导入 Postman 或 Insomnia,在测试中验证请求和响应,运行模拟服务器,呈现参考文档,并标出版本之间的破坏性变更。对于小型 API,生成的客户端可以完全取代官方 SDK;只要该文件随 API 一起进行版本管理,生成的客户端从机制上就能保持最新。对于 AI 编程助手来说,这个文件也是它为正确集成 API 所能读取的最有用的资料。
架构无法描述的是行为:何时重试、幂等机制如何运作、Webhook 如何签名。这些仍需要文字文档来说明。
示例
假设一个团队根据某 SMS 提供商的文件生成了 TypeScript 客户端。现在,编译器会拒绝遗漏必填字段的代码;消息类型也表明响应中包含分段数和价格,因此团队的成本跟踪代码是基于真实字段编写的,而不是靠猜测。
常见错误
- 只生成一次客户端,之后再也不重新生成,导致它与 API 逐渐脱节。
- 手工修改生成的代码,而下一次生成会将其覆盖。
- 让工具指向过时的下载副本,而不是已发布的文件。
在 SMSMeteor:API 以 OpenAPI 3.1 描述,发布在 /docs/openapi.yaml,并随 API 一起进行版本管理。包括 cURL、Python、Node、PHP 和 Go 在内的示例见 SDK 页面。测试密钥会像正式密钥一样响应,但不发送也不计费,因此在存入任何资金之前,就可以对生成的客户端进行端到端测试。
