OpenAPI — API-Spezifikation

Q: Sollte ich unter /openapi.json oder /.well-known/openapi.json ausliefern?

/openapi.json im Root ist die dominierende Konvention. Manche Agenten prüfen /.well-known/openapi.json als Fallback. Beides auszuliefern ist in Ordnung.

Q: Bestraft AgentGrade Sites mit nur deklarierten Zahlungsinfos?

Sites, deren OpenAPI x-payment-info deklariert, aber ohne Live-Verifikation, punkten positiv, aber unter Sites, bei denen der Live-Probe das deklarierte Protokoll bestätigt. Beides ist besser als gar kein Signal.

Q: Was ist mit x-mcp-server oder anderen Erweiterungen?

OpenAPIs x--Präfix ist offen. AgentGrade sucht derzeit nach x-payment-info an Deklarationen kostenpflichtiger Endpoints. Weitere agent-relevante Erweiterungen können hinzukommen, wenn sich das Ökosystem standardisiert.

Was ist OpenAPI?

OpenAPI (ursprünglich Swagger) ist die dominierende Spezifikation, um REST-APIs maschinenlesbar zu beschreiben. Ein OpenAPI-Dokument — typischerweise eine JSON- oder YAML-Datei unter /openapi.json oder /swagger.json — listet jeden Endpoint auf, das HTTP-Verb, die akzeptierten Parameter, das Response-Schema, das Authentifizierungsschema und alle Custom Extensions. Die 3.x-Version wird von der OpenAPI Initiative gepflegt, einem Linux-Foundation-Projekt mit Beiträgen von Google, Microsoft, IBM, Postman, SmartBear und anderen.

Für KI-Agenten ist OpenAPI der Unterschied zwischen Raten und Wissen, wie deine API-Oberfläche aussieht. Ein Agent, der dein OpenAPI-Dokument abrufen kann, hat dieselbe erstklassige Grundlage, die ein generiertes SDK einem menschlichen Entwickler gibt: jeder Endpoint, Parameter, Typ und jedes Beispiel, statisch auffindbar.

Warum OpenAPI für Agenten wichtig ist

Agenten, die REST-APIs aufrufen, haben ein Iterationskosten-Problem. Ohne Schema lautet die Schleife: Endpoint raten → aufrufen → Fehler parsen → Parameterform raten → erneut aufrufen → nächsten Fehler parsen. Drei bis fünf Roundtrips pro Endpoint sind typisch, und der Agent verbrennt bei jedem fehlgeschlagenen Aufruf Tokens und Zeit.

Mit OpenAPI kann der Agent:

Den richtigen Endpoint wählen, indem er die Felder summary und description mit der Absicht des Nutzers abgleicht.
Beim ersten Versuch einen gültigen Request bauen, indem er das Parameter-Schema liest — inklusive Pflichtfeldern, Typen und Enums.
Antworten korrekt parsen, indem er sich an das Response-Schema bindet, statt Regex zu improvisieren.
Die Authentifizierung entdecken über das securitySchemes-Objekt — inklusive x402-Zahlungsanforderungen über die x-payment-info-Erweiterung, nach der AgentGrade sucht.

Agenten, die auf einer Site OpenAPI finden, haben beim ersten Aufruf eine messbar höhere Erfolgsquote als Agenten, die Doku scrapen müssen. Deshalb ist eine veröffentlichte OpenAPI-Spezifikation einer der am höchsten gewichteten Checks, die AgentGrade auf Sites mit APIs ausführt.

So funktioniert OpenAPI

OpenAPI ist ein JSON- oder YAML-Dokument. Es beginnt mit Metadaten (info, servers), listet dann jeden Pfad unter paths auf und deklariert wiederverwendbare Schemas unter components. Tools lesen es per HTTP-Fetch — außer Standard-JSON-Verarbeitung ist kein SDK oder Parser nötig.

Ein minimales gültiges OpenAPI-3.0-Dokument:

{
  "openapi": "3.0.3",
  "info": {
    "title": "Catalog API",
    "version": "1.0.0",
    "description": "Search the product catalog and place orders."
  },
  "servers": [
    { "url": "https://api.example.com" }
  ],
  "paths": {
    "/search": {
      "get": {
        "summary": "Search the product catalog",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Search query string"
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Product" }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "price_usd": { "type": "number" }
        }
      }
    }
  }
}

Die meisten Web-Frameworks generieren das automatisch aus den Routen-Definitionen (FastAPI in Python, Hono in TypeScript, Echo in Go, Springs springdoc-openapi in Java). Von Hand schreiben ist selten nötig.

OpenAPI vs. andere Schichten für Agent-Lesbarkeit

Spec	Format	Was sie beantwortet	Wofür Agenten sie nutzen
OpenAPI	JSON/YAML	Endpoints, Parameter, Typen, Auth	Gültige Requests bauen
SKILL.md	Markdown + Frontmatter	Wie man diesen Service nutzt, in Prosa	Auswählen, welcher Endpoint aufgerufen wird
MCP-Manifest	JSON-RPC	Tools über persistente Verbindung	Den Server als langlebiges Tool aufrufen
llms.txt	Markdown	Was ist diese Site	Triage — ist diese Site relevant?
`ai-plugin.json`	JSON	Legacy-ChatGPT-Plugin-Metadaten	Plugin-Discovery (veraltet)

OpenAPI ist das Schema der Wahrheit. Die anderen Dateien verweisen darauf; Agenten validieren dagegen. Eine Site mit SKILL.md + OpenAPI gibt einem Agenten sowohl das Playbook als auch den formalen Vertrag.

Die `x-payment-info`-Erweiterung

OpenAPI unterstützt Custom-Extension-Felder mit dem Präfix x-. AgentGrade sucht nach einem x-payment-info-Objekt auf Operationsebene, das deklariert, ob ein Endpoint kostenpflichtig ist, den Preis, das Protokoll (x402, L402, MPP, SPT) und eine eventuelle Payment-URL.

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

Das macht das Kostenpflichtig-Signal maschinell prüfbar, ohne dass der Agent einen Probe-Request senden und eine 402-Antwort parsen muss. AgentGrade verifiziert, dass die deklarierten Zahlungsinfos zu einem Live-Probe passen — nur deklariert ohne Live-Verifikation punktet niedriger als deklariert + verifiziert.

Wer OpenAPI nutzt

OpenAPI ist wirklich universell. Große API-Plattformen (Stripe, Twilio, GitHub, Cloudflare, AWS über seinen OpenAPI-Generator) veröffentlichen OpenAPI-Spezifikationen als kanonische Referenz. Wichtige Framework-Integrationen:

FastAPI (Python) — generiert OpenAPI aus Type Hints
Hono + zod — laufzeitvalidierte TypeScript-Routen, die OpenAPI ausgeben
NestJS (TypeScript) — Decorator-getriebene OpenAPI-Generierung
Spring Boot + springdoc — annotationsbasiertes OpenAPI für Java
Echo + echo-swagger — OpenAPI-Generierung für Go
Rails + rswag — OpenAPI-Generierung für Ruby

Für Agenten heißt das praktisch: Jede moderne API der letzten fünf Jahre hat entweder OpenAPI oder kann es mit einer einzigen Abhängigkeit bekommen.

So fügst du OpenAPI zu deinem Service hinzu

Wähle einen Generator. Wenn dein Framework automatische OpenAPI-Generierung unterstützt, nutze sie. Handschriftliche Spezifikationen sind fehleranfällig und veralten.
Liefere sie unter einem stabilen Pfad aus. /openapi.json ist der konventionelle Ort; /swagger.json akzeptieren die meisten Tools. Root oder /.well-known/ sind beide in Ordnung.
Setze CORS. Erlaube Agent-Fetchern, das Dokument aus einem Browser-Kontext zu lesen: Access-Control-Allow-Origin: * auf dem Spec-Endpoint.
Deklariere servers mit der Produktions-URL. Ohne das bauen Agenten Request-URLs gegen den falschen Origin.
Ergänze description-Felder. Jeder Endpoint, jeder Parameter. Agenten lesen sie, um Endpoints auszuwählen und Semantik abzuleiten.
Deklariere x-payment-info, falls ein Endpoint eine Zahlung erfordert. Stimme es mit der Live-Antwort ab.
Verlinke aus llms.txt oder SKILL.md. Optional, hilft Agenten aber, die Spezifikation zu entdecken.

Häufige Fehler, die Scanner melden

Falscher Content-Type — die Spezifikation wird als text/html ausgeliefert (oft eine Swagger-UI-Seite) statt als application/json. Agenten, die die Spezifikation unter /openapi.json suchen, bekommen das UI-HTML und scheitern am Parsen.
Veraltete Spezifikation — die Datei listet Endpoints, die nicht mehr existieren, oder lässt neue aus. Auto-Generierung verhindert das.
Fehlendes servers[].url — Agenten, die dieses Feld zum Bauen von Request-URLs lesen, fallen auf den Origin der Spezifikation zurück, was oft falsch ist (z. B. Spec auf docs.example.com, API auf api.example.com).
Keine description an Endpoints — Agenten können den Pfad lesen, aber ohne Prosa-Beschreibungen können sie nicht zuverlässig zwischen ähnlichen Endpoints wählen.
Deklariertes x-payment-info passt nicht zum Live-Probe — behauptet, ein Endpoint sei kostenpflichtig, aber der Live-Request liefert 200 ohne Payment-Challenge, oder behauptet kostenlos, liefert aber 402.
CORS blockiert den Fetch — die Spezifikation wird ausgeliefert, aber ein fehlender Access-Control-Allow-Origin-Header hindert Agenten im Browser-Kontext am Lesen.

Häufig gestellte Fragen

Was ist der Unterschied zwischen OpenAPI und Swagger?

„Swagger“ war der ursprüngliche Name; 2015 wurde es bei der Übergabe an die Linux Foundation in OpenAPI umbenannt. SmartBear behält die Marke „Swagger“ für Tools (Swagger UI, Swagger Editor). Die Spezifikation heißt OpenAPI; das Tooling heißt oft noch Swagger.

Brauche ich OpenAPI, wenn ich SKILL.md habe?

Liefere beides aus, wenn du eine API hast. SKILL.md ist das „Playbook“ — Prosa, agent-lesbar. OpenAPI ist der „Vertrag“ — formal, maschinell validierbar. Agenten nutzen SKILL.md, um zu entscheiden, welchen Endpoint sie aufrufen, und OpenAPI, um den Aufruf korrekt zu bauen.

Sollte ich unter /openapi.json oder /.well-known/openapi.json ausliefern?

/openapi.json im Root ist die dominierende Konvention. Manche Agenten prüfen /.well-known/openapi.json als Fallback. Beides auszuliefern ist in Ordnung.

OpenAPI 3.0 vs. 3.1 vs. 2.0 — spielt das eine Rolle?

3.1 ist aktuell; 3.0 ist in Ordnung und breit unterstützt. 2.0 (das ursprüngliche „Swagger 2.0“-Format) wird noch erkannt, aber du solltest migrieren. Tools verarbeiten alle drei; Agenten interessiert die Versionslinie in der Regel nicht.

Kann ich OpenAPI für eine GraphQL-API ausliefern?

OpenAPI beschreibt REST. Bei GraphQL introspektieren Agenten das Schema direkt über den GraphQL-Endpoint. Manche Sites veröffentlichen sowohl ein OpenAPI-Shim als auch den GraphQL-Endpoint.

Bestraft AgentGrade Sites mit nur deklarierten Zahlungsinfos?

Sites, deren OpenAPI x-payment-info deklariert, aber ohne Live-Verifikation, punkten positiv, aber unter Sites, bei denen der Live-Probe das deklarierte Protokoll bestätigt. Beides ist besser als gar kein Signal.

Was ist mit x-mcp-server oder anderen Erweiterungen?

OpenAPIs x--Präfix ist offen. AgentGrade sucht derzeit nach x-payment-info an Deklarationen kostenpflichtiger Endpoints. Weitere agent-relevante Erweiterungen können hinzukommen, wenn sich das Ökosystem standardisiert.

Wie groß darf eine OpenAPI-Spezifikation werden, bevor Agenten Probleme bekommen?

Multi-MB-Spezifikationen sind bei großen API-Plattformen üblich (Stripes ist ~10 MB). Agenten können sie in der Regel problemlos abrufen und parsen, laden aber womöglich nicht die volle Spezifikation in ihren Kontext — sie suchen oder chunken. Halte description-Felder knapp; dort landet das meiste Token-Gewicht.

Reifegrad der Spezifikation

Universeller Industriestandard. OpenAPI 3.x wird von der OpenAPI Initiative unter der Linux Foundation gepflegt. Unterstützt von praktisch jedem API-Tool, Code-Generator, KI-Coding-Assistenten und modernen Web-Framework.

Mehr erfahren

OpenAPI Specification — offizielle Spezifikation und Doku
Swagger Editor — Spezifikationen schreiben und validieren
SKILL.md — begleitende Prosa-Schicht für Agenten
x402 — Zahlungsprotokoll, das sich über x-payment-info integriert
Agent Readiness — wie OpenAPI ins große Ganze passt