# 一份 OpenAPI 规范，如何同时写给人和 Agent

> Speakeasy 用 OpenAPI 构建 50 多个 MCP 服务器后发现，工具多到 200 个，模型就会选错。

原文: https://fdetimes.net/zh/tools/openapi-swagger-stoplight-readme-llm-spec/

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 团队需要对接你正在开发的订单查询服务。后端还没完成，但双方现在就得商定请求和响应的格式。第一步是编写规范，针对单个端点的最小版本大致如下：

```yaml
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 个工具的警告正是原因所在：把每个操作都变成工具，会淹没模型的上下文。

**要点:** 写给人的规范要完整；写给 Agent 的规范要精选，并明确说明每个端点何时使用。

第二个问题是描述。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 共同阅读的接口。

**本周动手试试:**

- 选一个你正在开发的内部 API，为其中最重要的三个端点编写 OpenAPI 规范，并运行 Spectral。
- 用这份规范启动 Prism，发送一个数据类型错误的请求，看看 Mock 服务器如何报告校验错误。
- 按“何时使用、需要什么、返回什么”的格式重写一个端点的描述，再与原来的版本对比。

## 信源

- [Swagger (SmartBear) – official website](https://swagger.io/)

- [OpenAPI Initiative](https://www.openapis.org/)

- [OpenAPI Specification v3.2.1](https://spec.openapis.org/oas/latest.html)

- [A brief history of the OpenAPI Specification (Mike Ralphson, DEV Community)](https://dev.to/mikeralphson/a-brief-history-of-the-openapi-specification-3g27)

- [Stoplight](https://stoplight.io/)

- [stoplightio (GitHub organization)](https://github.com/stoplightio)

- [Redocly/redoc (GitHub README)](https://github.com/Redocly/redoc)

- [MCP servers – ReadMe Docs](https://docs.readme.com/main/docs/mcp-servers)

- [Generating MCP servers from OpenAPI: Lessons from building 50+ production MCP servers (Georges Haidar, Speakeasy)](https://www.speakeasy.com/blog/generating-mcp-from-openapi-lessons-from-50-production-servers)
