## 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](/kb/de/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:

```json
{
  "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](/kb/de/skills)** | Markdown + Frontmatter | *Wie man diesen Service nutzt, in Prosa* | Auswählen, welcher Endpoint aufgerufen wird |
| **[MCP](/kb/de/mcp)-Manifest** | JSON-RPC | *Tools über persistente Verbindung* | Den Server als langlebiges Tool aufrufen |
| **[llms.txt](/kb/de/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](/kb/de/x402), [L402](/kb/de/l402), [MPP](/kb/de/mpp), [SPT](/kb/de/spt)) und eine eventuelle Payment-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"
        }
      }
    }
  }
}
```

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

1. **Wähle einen Generator.** Wenn dein Framework automatische OpenAPI-Generierung unterstützt, nutze sie. Handschriftliche Spezifikationen sind fehleranfällig und veralten.
2. **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.
3. **Setze CORS.** Erlaube Agent-Fetchern, das Dokument aus einem Browser-Kontext zu lesen: `Access-Control-Allow-Origin: *` auf dem Spec-Endpoint.
4. **Deklariere `servers` mit der Produktions-URL.** Ohne das bauen Agenten Request-URLs gegen den falschen Origin.
5. **Ergänze `description`-Felder.** Jeder Endpoint, jeder Parameter. Agenten lesen sie, um Endpoints auszuwählen und Semantik abzuleiten.
6. **Deklariere `x-payment-info`**, falls ein Endpoint eine Zahlung erfordert. Stimme es mit der Live-Antwort ab.
7. **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](/kb/de/skills) 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](https://www.openapis.org/) — offizielle Spezifikation und Doku
- [Swagger Editor](https://editor.swagger.io/) — Spezifikationen schreiben und validieren
- [SKILL.md](/kb/de/skills) — begleitende Prosa-Schicht für Agenten
- [x402](/kb/de/x402) — Zahlungsprotokoll, das sich über `x-payment-info` integriert
- [Agent Readiness](/agent-readiness) — wie OpenAPI ins große Ganze passt