## 什么是 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](/kb/zh/x402) 支付要求。

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

## OpenAPI 如何工作

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

最小有效的 OpenAPI 3.0 文档：

```json
{
  "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](/kb/zh/skills)** | Markdown + frontmatter | *如何用散文使用此服务* | 选择调用哪个端点 |
| **[MCP](/kb/zh/mcp) 清单** | JSON-RPC | *持久连接上公开的工具* | 将服务器作为长期工具调用 |
| **[llms.txt](/kb/zh/llms-txt)** | Markdown | *这个网站是什么* | 分流——相关吗？ |
| **`ai-plugin.json`** | JSON | *遗留 ChatGPT 插件元数据* | 插件发现（已弃用） |

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

## `x-payment-info` 扩展

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

```json
{
  "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](/kb/zh/skills),还需要 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](https://www.openapis.org/) — 官方规范和文档
- [Swagger Editor](https://editor.swagger.io/) — 编写和验证规范
- [SKILL.md](/kb/zh/skills) — 代理的配套散文层
- [x402](/kb/zh/x402) — 通过 `x-payment-info` 集成的支付协议