← 知识库

OpenAPI — API 规范

什么是 OpenAPI？

OpenAPI（最初称为 Swagger）是以机器可读形式描述 REST API 的主导规范。OpenAPI 文档——通常是位于 /openapi.json 或 /swagger.json 的 JSON 或 YAML 文件——枚举每个端点、HTTP 动词、每个端点接受的参数、响应模式、认证方案和任何自定义扩展。3.x 版本由 OpenAPI Initiative 维护,这是 Linux Foundation 的一个项目,贡献者包括 Google、Microsoft、IBM、Postman、SmartBear 等。

对于 AI 代理,OpenAPI 是猜测你的 API 表面和了解它之间的区别。能够获取你的 OpenAPI 文档的代理拥有与生成的 SDK 提供给人类开发者相同的一流便利性。

为什么 OpenAPI 对代理重要

调用 REST API 的代理面临迭代成本问题。没有 schema,循环是：猜测端点 → 调用 → 解析错误 → 猜测参数形式 → 再次调用 → 解析下一个错误。每个端点 3-5 次往返是典型的,代理在每次失败的调用上消耗 token 和时钟时间。

有了 OpenAPI,代理可以：

• 通过根据用户意图阅读 summary 和 description 字段来选择正确的端点。
• 通过阅读参数 schema 首次构建有效请求。
• 通过绑定到响应 schema 正确解析响应。
• 从 securitySchemes 对象发现认证——包括通过 AgentGrade 寻找的 x-payment-info 扩展的 x402 支付要求。

在网站上找到 OpenAPI 的代理首次调用成功率比必须抓取文档的代理可测量地更高。

OpenAPI 如何工作

OpenAPI 是 JSON 或 YAML 文档。它以元数据（info、servers）开始,然后在 paths 下枚举每个路径,然后在 components 下声明可重用的 schema。

最小有效的 OpenAPI 3.0 文档：

{
  "openapi": "3.0.3",
  "info": {
    "title": "Catalog API",
    "version": "1.0.0"
  },
  "servers": [
    { "url": "https://api.example.com" }
  ],
  "paths": {
    "/search": {
      "get": {
        "summary": "Search the product catalog",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Search results" }
        }
      }
    }
  }
}

大多数 Web 框架从路由定义自动生成此内容（Python 中的 FastAPI、TypeScript 中的 Hono、Go 中的 Echo、Java 中 Spring 的 springdoc-openapi）。手动编写很少必要。

OpenAPI 与其他代理可读层

规范	格式	回答什么	代理用途
OpenAPI	JSON/YAML	端点、参数、类型、认证	构建有效请求
SKILL.md	Markdown + frontmatter	如何用散文使用此服务	选择调用哪个端点
MCP 清单	JSON-RPC	持久连接上公开的工具	将服务器作为长期工具调用
llms.txt	Markdown	这个网站是什么	分流——相关吗？
ai-plugin.json	JSON	遗留 ChatGPT 插件元数据	插件发现（已弃用）

OpenAPI 是记录的 schema。其他文件引用它;代理对它进行验证。

x-payment-info 扩展

OpenAPI 支持带 x- 前缀的自定义扩展字段。AgentGrade 寻找操作级别的 x-payment-info 对象,声明端点是否付费、价格、协议（x402、L402、MPP、SPT）和任何支付 URL。

{
  "paths": {
    "/api/order": {
      "post": {
        "summary": "Place an order",
        "x-payment-info": {
          "required": true,
          "protocol": "x402",
          "price_usd": "0.10",
          "currency": "USDC",
          "network": "base"
        }
      }
    }
  }
}

这使得付费端点信号可由机器检查,而无需代理发出探测请求并解析 402 响应。

谁在使用 OpenAPI

OpenAPI 真正具有普遍性。主要 API 平台（Stripe、Twilio、GitHub、Cloudflare、通过其 OpenAPI 生成器的 AWS）将 OpenAPI 规范作为规范参考发布。主要的框架采用：

• FastAPI（Python）——从类型提示生成 OpenAPI
• Hono + zod——发出 OpenAPI 的运行时验证 TypeScript 路由
• NestJS（TypeScript）——装饰器驱动的 OpenAPI 生成
• Spring Boot + springdoc——Java 基于注解的 OpenAPI
• Echo + echo-swagger——Go OpenAPI 生成
• Rails + rswag——Ruby OpenAPI 生成

如何将 OpenAPI 添加到你的服务

1. 选择生成器。 如果你的框架支持自动 OpenAPI 生成,使用它。
2. 在稳定路径提供。 /openapi.json 是惯例位置。
3. 设置 CORS。 允许代理获取器从浏览器上下文读取文档。
4. 用生产 URL 声明 servers。
5. 添加 description 字段。 每个端点,每个参数。
6. 如果任何端点需要付款,声明 x-payment-info。
7. 从 llms.txt 或 SKILL.md 链接。 可选但有帮助。

扫描器标记的常见错误

• 内容类型错误——规范作为 text/html（通常是 Swagger UI 页面）而不是 application/json 提供。
• 过时的规范——文件列出不再存在的端点或省略新的端点。
• 缺少 servers[].url——读取此字段的代理对错误的源构造请求 URL。
• 端点上没有 description——代理无法可靠地在类似端点之间选择。
• 声明的 x-payment-info 与实时探测不匹配。
• CORS 阻止获取。

FAQ

OpenAPI 和 Swagger 之间的区别是什么？

"Swagger" 是原始名称;2015 年捐赠给 Linux Foundation 时更名为 OpenAPI。SmartBear 保留了工具（Swagger UI、Swagger Editor）的 "Swagger" 品牌。

如果我有 SKILL.md,还需要 OpenAPI 吗？

如果你有 API,两个都发布。SKILL.md 是"操作手册"——散文。OpenAPI 是"合同"——正式。

我应该在 /openapi.json 还是 /.well-known/openapi.json 提供？

根目录的 /openapi.json 是主流惯例。

OpenAPI 3.0 vs 3.1 vs 2.0——重要吗？

3.1 是当前的;3.0 也很好且得到广泛支持。

我能为 GraphQL API 提供 OpenAPI 吗？

OpenAPI 描述 REST。对于 GraphQL,代理直接通过 GraphQL 端点进行 schema introspection。

AgentGrade 会惩罚只有声明支付信息的网站吗？

具有声明 x-payment-info 但没有实时验证的 OpenAPI 的网站会得到积极评分,但低于实时探测确认声明协议的网站。

x-mcp-server 或其他扩展呢？

OpenAPI 的 x- 前缀是开放的。AgentGrade 目前寻找 x-payment-info。

OpenAPI 规范在代理遇到困难之前可以多大？

多 MB 的规范在大型 API 平台上很常见（Stripe 的约 10MB）。

规范成熟度

普遍的行业标准。 OpenAPI 3.x 由 Linux Foundation 下的 OpenAPI Initiative 维护。

了解更多

• OpenAPI Specification — 官方规范和文档
• Swagger Editor — 编写和验证规范
• SKILL.md — 代理的配套散文层
• x402 — 通过 x-payment-info 集成的支付协议

相关阅读：什么是 AI 智能体就绪？