OpenAPI / Swagger（API规范）
AI TERM术语词条OpenAPI Specification
术语释义
REST API 的描述标准：用 JSON 或 YAML 定义接口路径、参数与响应，让文档、SDK 与 AI 工具自动生成，是 AI 接入既有系统的通用语言。
OpenAPI（API 规范，原名 Swagger）是用 JSON 或 YAML 描述 REST API 的行业标准，一份文件即可说明每个接口的路径、参数、请求体、响应结构与鉴权方式。它对 AI 开发格外重要：几乎所有主流 AI API 都提供这类描述文件，而智能体（Agent）可以直接读取描述理解接口用法并自动发起调用。它也因此成为 AI 与既有软件系统之间的通用语言。
一份规范能带来什么
- 文档自动化：由规范文件生成交互式接口文档，改代码即改文档，避免文档与实现脱节。
- 代码自动生成：自动生成多语言客户端 SDK、服务端桩代码与测试用例，减少手写样板。
- 契约先行：前后端与协作方先对齐接口形状，联调阶段的问题提前暴露在设计阶段。
- AI 工具集成：模型上下文协议（MCP，Model Context Protocol）可从描述自动生成可调用工具，智能体平台也支持直接导入规范文件作为能力来源。
与 MCP 的关系
二者互补而非替代。OpenAPI 描述的是传统 REST API，关注 HTTP 方法、状态码与数据结构；MCP（Model Context Protocol，模型上下文协议）描述的是面向 AI 原生的工具接口，关注模型如何发现并调用能力。实践中常见做法是先用 OpenAPI 描述既有服务，再通过适配层把它包装成 MCP 工具，让智能体无需为每个系统单独开发即可复用现有能力，也避免了两套描述长期分叉。
AI 时代的角色
大模型可以用自然语言理解接口描述，据此自动构造调用参数；当接口返回参数校验错误时，模型能读懂错误信息并调整调用方式，形成自我纠错的循环。这让接口描述从“给人看的文档”变成“给模型看的说明书”：描述是否准确、示例是否完整，直接影响智能体的调用成功率，含糊字段名与缺失示例都会变成模型猜错的来源。
实践要点
- 描述要可机读：字段类型、必填项、枚举取值与错误码都应写清楚，含糊的描述模型只能靠猜。
- 提供可运行示例：完整的请求与响应示例能显著提升模型构造调用的准确度。
- 显式声明鉴权与限流：在规范中标注鉴权方式与限流策略，避免智能体触发保护性封禁。
- 避免当作纯文档：只写给人看的说明、不维护结构化规范文件，就放弃了代码生成与工具生成的价值。
