一份 OpenAPI 规范,如何同时写给人和 Agent
Speakeasy 用 OpenAPI 构建 50 多个 MCP 服务器后发现,工具多到 200 个,模型就会选错。
要点速览
- OpenAPI 是标准;Swagger、Stoplight、Redoc 和 ReadMe 是基于它的工具。
- 一份好的规范可以生成文档、Mock 服务器、客户端,以及供 AI 助手使用的 MCP 服务器。
- 不要把所有端点都暴露给 LLM:工具太多会让模型混乱,而写给人看的描述并不适合机器。
Speakeasy 的 Georges Haidar 所在团队用 OpenAPI 文件构建了 50 多个生产环境 MCP 服务器,他从中得出一条教训:模型要在 200 个工具里做选择时,上下文窗口会过载,模型就会混乱。这一观察同时点出了当今使用最广的 API 描述标准的长处和陷阱。
长处在于,一份规范文件如今可以服务两类读者。客户的集成团队通过文档站点阅读它;Agent 则把它当作一份工具清单。陷阱在于,这两类读者需要的东西不一样。
如果你想成为前线部署工程师(FDE),应把这当作一项早该掌握的技能。客户问你的系统如何对接他们的企业资源计划(ERP)系统,或者希望 Agent 调用某个内部 API 时,一份干净的规范就是最先摆上桌面的东西。
OpenAPI 是标准,Swagger 是工具
许多开发者至今仍把这两个名字混着用,原因在历史。Swagger 由 Tony Tam 于 2009 年在 Wordnik 创建。2015 年 12 月,SmartBear 把这份规范交给 Linux Foundation 旗下的一个开放治理组织,OpenAPI 2.0 与 Swagger 2.0 完全相同。
此后,OpenAPI 成为由 OpenAPI Initiative 维护的标准。这份规范以独立于任何编程语言的方式描述 HTTP API,官网上的最新版本是 3.2.1。Swagger 则是 SmartBear 围绕这一标准打造的工具集。
它的开源套件包括:Editor,用于在浏览器中编写规范;UI,用于查看和试用 API;Codegen,用于生成客户端库、服务端桩代码和文档。
Stoplight 是一个面向设计优先(design-first)的平台,即先写规范、再写代码;它经收购后如今也归属 SmartBear。Redoc 是另一个开源工具,专门根据规范生成文档,支持 OpenAPI 3.1、3.0 和 Swagger 2.0。
招聘启事里提到“Swagger”或“OpenAPI”时,可以理解为要求的是同一种技能:用机器可读的方式描述 API。
一份规范,五个步骤
设想一家物流公司,其 IT 团队需要对接你正在开发的订单查询服务。后端还没完成,但双方现在就得商定请求和响应的格式。第一步是编写规范,针对单个端点的最小版本大致如下:
openapi: 3.1.0
info:
title: Order Status API
version: 0.1.0
paths:
/orders/{order_id}:
get:
operationId: getOrderStatus
summary: 获取单个订单的状态
description: >
当用户询问某个具体订单在哪里时使用。
需要字符串类型的 order_id;不要用于列出多个订单。
parameters:
- name: order_id
in: path
required: true
schema: { type: string }
responses:
'200':
description: 订单的当前状态
(summary 写的是“获取单个订单的状态”。description 写的是:“当用户询问某个具体订单在哪里时使用。需要字符串类型的 order_id;不要用于列出多个订单。”)
第二步是运行 Spectral。它是 Stoplight 出品的开源 JSON/YAML 检查工具(linter),可以自动执行风格规范。Spectral 支持 OpenAPI 2 到 3.1,以及 Arazzo 和 AsyncAPI,因此可以接入 CI,阻止任何人合并缺少 operationId 或描述的规范。
第三步是 Prism,同样来自 Stoplight。它能把 OpenAPI 文件或 Postman Collection 变成一个带校验的 Mock 服务器。真正的后端还在开发时,客户的 IT 团队今天就能开始调用,传错数据类型会返回错误。这通常是最快的办法,能在 schema 上的误解变成上线时的 bug 之前把它们暴露出来。
第四步是文档:Swagger UI 或 Redoc 用同一份文件构建文档站点;客户需要的话,Swagger Codegen 还能生成 SDK。没人需要手写一份 wiki 页面,然后忘了更新。
当读者是 LLM
第五步最容易出问题。ReadMe 能直接从 OpenAPI 规范生成 MCP 服务器,其中 get-endpoint 工具用于查看单个端点,execute-request 工具用于调用真实 API 并返回结果。客户的 Agent 读取规范,选择端点,然后发起调用。
默认情况下,规范中的每个端点都会暴露给 AI 助手,你可以逐个开启或关闭。如果客户的 API 有 180 个端点,而订单查询场景下 Agent 只需要其中 6 个,就把另外 174 个关掉。Speakeasy 关于 200 个工具的警告正是原因所在:把每个操作都变成工具,会淹没模型的上下文。
第二个问题是描述。Haidar 直言,OpenAPI 的描述并不是为 LLM 设计的。“获取单个订单的状态”对开发者来说足够了,但模型需要知道什么时候该用某个端点、什么时候不该用。所以上面示例中的描述要明确写出“不要用于列出多个订单”。
需要提前了解的局限
OpenAPI 是针对 HTTP API 的标准。如果客户运行的是事件驱动系统,对应的标准是 AsyncAPI;Spectral 可以检查它,但上文提到的 ReadMe MCP 功能,文档中写明是从 OpenAPI 规范生成的,因此在向客户做出任何承诺之前要另行确认。规范也只有在持续维护时才是正确的:规范错到什么程度,Prism 的 Mock 和 Redoc 的文档就错到什么程度。
也不要把“有 MCP 服务器”等同于“Agent 能用好它”。execute-request 工具调用的是真实 API,所以权限和暴露端点的范围需要与客户商定,而不是交给默认设置。
三个常见错误,以及一个规避练习
第一个错误是保留默认设置,把所有端点都暴露给 Agent,然后对模型选错端点感到意外。第二个错误是沿用写给人看的描述,比如一行 summary,而没有讲清楚某个端点何时该用、何时不该用。
第三个错误是把规范当成写完就不管的文档,不在 CI 中做检查,任由它与代码脱节,直到 Mock 和文档也一并出错。
练习:在上面的 YAML 文件里新增一个 GET /orders 端点,按客户列出订单。为两个端点编写描述,让不会写代码的人也能在“查询单个订单”和“列出多个订单”之间正确选择,然后运行 Spectral 和 Prism。如果你必须读 schema 才能区分这两个端点,模型也会很吃力。
先学什么
从标准入手,而不是从工具入手。阅读规范中的 paths、parameters 和 components/schemas 部分,为一个你熟悉的 API 手写一份规范,再对它运行 Spectral 和 Prism。熟练之后,再加上第五步:逐一检查每条描述是否足以让模型做出正确选择。
简历上不要笼统地写“熟悉 Swagger”。要写明你搭建过规范优先的工作流:在 CI 中做检查、为集成伙伴提供 Mock、为 Agent 精选端点。这三点能让招聘经理看到,你明白一份规范要同时服务人和机器。
规范过去只是为了关掉一个工单而写的东西。如今,它是客户的 IT 团队和他们的 Agent 共同阅读的接口。
这篇文章对你有帮助吗?
感谢你的反馈!
9 个信源
- Swagger (SmartBear) – official website
- OpenAPI Initiative
- OpenAPI Specification v3.2.1 · 2026-09-10
- A brief history of the OpenAPI Specification (Mike Ralphson, DEV Community) · 2018-12-17
- Stoplight
- stoplightio (GitHub organization)
- Redocly/redoc (GitHub README)
- MCP servers – ReadMe Docs · 2026-10-01
- Generating MCP servers from OpenAPI: Lessons from building 50+ production MCP servers (Georges Haidar, Speakeasy) · 2025-06-24