一句话定义：OpenAPI 规范（OpenAPI Specification，常缩写 OAS）是一种用 JSON 或 YAML 描述 HTTP 接口的通用格式——它把「这个接口叫什么、收什么参数、返回什么、怎么鉴权」写成一份机器可读的文档。
它到底描述了什么
一份 OpenAPI 文档通常包含几层信息：有哪些路径（path），每个路径支持哪些方法（GET/POST 等），每个操作（operation）的唯一标识和说明，需要哪些参数（类型、是否必填、示例值），请求体长什么样，以及返回结构和鉴权方式。
打个比方：它像是家具说明书里的组装图纸。螺丝、木板、孔位都是同一批零件，但有人画成图，任何人——不管是不是原厂工人——照着图都能装出来。没有图纸，你只能靠猜或者打电话问客服。
为什么它突然变得很关键
模型本身看不见你的服务器，它能看见的只有你递给它的那份描述。所以这份文档的措辞，直接决定调用能不能成功。
- 参数写成
city: string, 必填, 示例：上海，模型基本一次就能拼出正确请求。 - 参数写成
input: string，模型只能瞎猜，十次里错八次。 - 接口说明写「创建订单」，模型知道这是有副作用的操作；写「处理数据」，模型不知道要不要谨慎。
换句话说，给智能体的工具描述，本质上是你写给模型的提示词（prompt）的一部分，只不过它是结构化的。
和相邻概念的区别
| 名称 | 描述的对象 | 典型使用场景 |
|---|---|---|
| OpenAPI 规范 | 一整个 HTTP API：路径、方法、参数、返回、鉴权 | 后端文档、网关、也给智能体当工具清单 |
| JSON Schema | 单个数据结构的形状（字段、类型、必填） | 被 OpenAPI 借用描述参数，也是函数调用（function calling）的参数格式 |
| MCP（Model Context Protocol） | 模型与工具之间如何通信与发现工具 | 智能体客户端的运行时协议 |
另外要澄清一个常见混淆：Swagger 最早是这套描述格式的名字，后来规范改名为 OpenAPI 规范，Swagger 主要留作配套工具集的名字（如接口文档界面、编辑器）。日常口语里两者常被混用，但严格说不是一回事。
MCP 和 OpenAPI 也不是替代关系：OpenAPI 描述的是你已经存在的 HTTP 接口，MCP 管的是模型在运行时怎么把这些能力接进来。社区里常见的做法，是把现成的 OpenAPI 文档转换成 MCP 工具，省去重写一遍的功夫。
对你的实际意义
如果你在提供 API：把每个操作的说明、参数含义、单位、取值范围、错误码写清楚，收益不只是给人看文档，更是让智能体调得准。含糊的字段名和缺失的示例，是工具调用失败的头号原因。有副作用的接口（下单、转账、删除）尤其要标注清楚，避免模型自作主张。
如果你在做智能体：优先找官方维护的 OpenAPI 文档，而不是从网页上猜接口；同时留意文档里的接口粒度，一个操作包办十件事的接口，模型很难用对。
规范的细节（字段名、版本差异、扩展写法）以官方页面为准，实现时对着校验工具跑一遍，比读十篇文章都管用。