AgentGrade
EnglishEspañol日本語中文
← ナレッジベース

OpenAPI — API仕様

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 があれば、エージェントは：

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

OpenAPI の仕組み

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

最小限の有効な 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 と他のエージェント対応レイヤー

仕様形式何に答えるかエージェントの用途
OpenAPIJSON/YAMLエンドポイント、パラメータ、型、認証有効なリクエスト構築
SKILL.mdMarkdown + フロントマターこのサービスの使い方を散文でどのエンドポイントを呼ぶか選択
MCP マニフェストJSON-RPC持続的接続上のツールサーバーを長寿命ツールとして呼び出し
llms.txtMarkdownこのサイトは何かトリアージ — 関連あるか？
ai-plugin.jsonJSONレガシー ChatGPT プラグインメタデータプラグイン発見（廃止）

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

x-payment-info 拡張

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

{
  "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 仕様を正規リファレンスとして公開しています。主要なフレームワーク採用：

サービスに OpenAPI を追加する方法

  1. ジェネレータを選ぶ。 フレームワークが OpenAPI 自動生成をサポートする場合は使用してください。
  2. 安定したパスで配信。 /openapi.json が慣例の場所です。
  3. CORS を設定。 ブラウザコンテキストからエージェントフェッチャーがドキュメントを読めるように。
  4. 本番 URL で servers を宣言。
  5. description フィールドを追加。 すべてのエンドポイント、すべてのパラメータ。
  6. エンドポイントが支払いを必要とする場合は x-payment-info を宣言。
  7. llms.txt または SKILL.md からリンク。 オプションだが役立つ。

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

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 エンドポイント経由でスキーマを直接イントロスペクトします。

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 によって維持されています。

詳細

関連: AIエージェント対応とは何か？