## OpenAPI とは？

OpenAPI（元は Swagger）は、REST API を機械可読な形式で記述するための支配的な仕様です。OpenAPI ドキュメント — 通常は `/openapi.json` または `/swagger.json` の JSON または YAML ファイル — は、すべてのエンドポイント、HTTP 動詞、各エンドポイントが受け入れるパラメータ、レスポンススキーマ、認証スキーム、カスタム拡張を列挙します。3.x バージョンは OpenAPI Initiative によって維持されており、Google、Microsoft、IBM、Postman、SmartBear などの貢献者がいる Linux Foundation のプロジェクトです。

AI エージェントにとって、OpenAPI はあなたの API 表面を推測することと*知っている*ことの違いです。OpenAPI ドキュメントを取得できるエージェントは、生成された SDK が人間の開発者に与えるのと同じファーストクラスのアフォーダンスを持ちます。

## OpenAPI がエージェントにとって重要な理由

REST API を呼び出すエージェントは、イテレーションコストの問題に直面します。スキーマなしでは、ループは：エンドポイントを推測 → 呼び出し → エラーを解析 → パラメータ形式を推測 → 再度呼び出し → 次のエラーを解析。エンドポイントあたり 3-5 ラウンドトリップが典型的で、失敗した呼び出しごとにエージェントはトークンと時間を消費します。

OpenAPI があれば、エージェントは：

- ユーザーの意図に対して `summary` と `description` フィールドを読んで**正しいエンドポイントを選択**できます。
- パラメータスキーマを読んで**初回で有効なリクエストを構築**できます。
- レスポンススキーマにバインドして**レスポンスを正しく解析**できます。
- `securitySchemes` オブジェクトから**認証を発見**できます — AgentGrade が探す `x-payment-info` 拡張による [x402](/kb/ja/x402) 支払い要件を含めて。

サイトで OpenAPI を見つけたエージェントは、ドキュメントをスクレイピングしなければならないエージェントよりも測定可能に高いレートで初回呼び出しで成功します。

## OpenAPI の仕組み

OpenAPI は JSON または YAML ドキュメントです。メタデータ（`info`、`servers`）で開き、`paths` の下にすべてのパスを列挙し、`components` の下に再利用可能なスキーマを宣言します。

最小限の有効な 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/ja/skills)** | Markdown + フロントマター | *このサービスの使い方を散文で* | どのエンドポイントを呼ぶか選択 |
| **[MCP](/kb/ja/mcp) マニフェスト** | JSON-RPC | *持続的接続上のツール* | サーバーを長寿命ツールとして呼び出し |
| **[llms.txt](/kb/ja/llms-txt)** | Markdown | *このサイトは何か* | トリアージ — 関連あるか？ |
| **`ai-plugin.json`** | JSON | *レガシー ChatGPT プラグインメタデータ* | プラグイン発見（廃止） |

OpenAPI は記録のスキーマです。他のファイルはそれを参照し、エージェントはそれに対して検証します。

## `x-payment-info` 拡張

OpenAPI は `x-` プレフィックスのカスタム拡張フィールドをサポートします。AgentGrade は、エンドポイントが有料か、価格、プロトコル（[x402](/kb/ja/x402)、[L402](/kb/ja/l402)、[MPP](/kb/ja/mpp)、[SPT](/kb/ja/spt)）、支払い URL を宣言する operation レベルの `x-payment-info` オブジェクトを探します。

```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、AWS の OpenAPI ジェネレータ経由）が 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 からリンク。** オプションだが役立つ。

## スキャナーがフラグを立てる一般的なエラー

- **content-type が間違っている** — 仕様が `application/json` ではなく `text/html`（しばしば Swagger UI ページ）として配信されている。
- **古い仕様** — ファイルが存在しないエンドポイントをリストしたり、新しいものを省略したりしている。
- **`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/ja/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 エンドポイント経由でスキーマを直接イントロスペクトします。

**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/ja/skills) — エージェント向け付属散文レイヤー
- [x402](/kb/ja/x402) — `x-payment-info` 経由で統合する支払いプロトコル