API-Dokumentation automatisiert generieren mit Claude

1. Ausgangslage: Warum API-Dokumentation in Magento-Projekten veraltet

In den meisten Magento-Projekten entsteht API-Dokumentation als Nebenprodukt, nicht als Teil des eigentlichen Entwicklungsprozesses. Ein neuer REST-Endpunkt wird in webapi.xml deklariert, das zugehörige Service-Interface bekommt eine Implementierung, der Sprint ist fertig, und die Dokumentation in Confluence oder einem separaten Wiki bleibt beim alten Stand stehen. Nach einigen Monaten stimmen Feldnamen, Pflichtparameter und Fehlercodes nicht mehr mit dem tatsächlichen Verhalten der API überein.

Das Problem verschärft sich bei extern genutzten APIs: Integrationspartner, die ein Magento-Backend an ein PIM, ein ERP oder eine Marketing-Automation anbinden, verlassen sich auf die dokumentierten Verträge. Weicht die Realität ab, entstehen Supportanfragen, die eigentlich vermeidbar wären. Claude Code kann hier ansetzen, weil es Code direkt lesen und daraus eine erste, strukturierte Beschreibung ableiten kann, noch bevor ein Mensch die Doku manuell nachträgt. Entscheidend ist dabei, dass die generierte Beschreibung als Entwurf behandelt wird, nicht als fertiges Ergebnis.

2. Von Controller und webapi.xml zur OpenAPI-Beschreibung

Magento bietet mit dem eingebauten Schema-Endpunkt unter /rest/V1/schema?services=all bereits eine automatisch generierte, technisch korrekte API-Beschreibung. Sie enthält jedoch kaum menschenlesbare Beschreibungen, keine Beispielwerte und keine Hinweise auf Geschäftslogik, die sich nicht direkt aus der Typsignatur ablesen lässt. Genau an dieser Stelle wird Claude Code sinnvoll eingesetzt: nicht als Ersatz für den Schema-Endpunkt, sondern als Werkzeug, das die technische Struktur um verständliche Beschreibungen, Beispiele und Kontext ergänzt.

Der Ausgangspunkt ist immer der Code selbst: etc/webapi.xml definiert Route, HTTP-Methode und ACL-Resource, das zugehörige Api/*Interface.php definiert Parameter- und Rückgabetypen mit PHPDoc-Kommentaren. Claude Code liest beide Dateien zusammen mit den referenzierten Datenmodellen und leitet daraus eine OpenAPI-3.0-Beschreibung ab, die Pfade, Parameter, Schemas und mögliche Fehlerantworten enthält. Wichtig ist, das Modell explizit anzuweisen, nur Felder zu dokumentieren, die tatsächlich im Interface vorkommen, um Erfindungen zu vermeiden.

#!/usr/bin/env bash
# generate-api-docs.sh - Draft OpenAPI descriptions from Magento webapi.xml and interfaces
set -euo pipefail

MODULE_PATH="app/code/Mironsoft/SeoSuite"

claude --print \
  "Read ${MODULE_PATH}/etc/webapi.xml and all files in ${MODULE_PATH}/Api/. \
   Generate an OpenAPI 3.0 fragment in YAML for every declared REST route. \
   Include request/response schemas derived from the *Interface.php return types \
   and @param/@return PHPDoc annotations. Do not invent fields that are not \
   present in the interface or its data model." \
  > "${MODULE_PATH}/doc/openapi-draft.yaml"

echo "[INFO] Draft written to ${MODULE_PATH}/doc/openapi-draft.yaml, review required"

3. Claude Code als Werkzeug: Kontext, Prompting und Grenzen

Die Qualität der generierten Dokumentation hängt fast vollständig davon ab, welcher Kontext dem Modell zur Verfügung gestellt wird. Ein Prompt, der nur nach "OpenAPI-Dokumentation für die SeoSuite-API" fragt, liefert generische, teilweise erfundene Ergebnisse. Ein Prompt, der explizit auf webapi.xml, die konkreten Interface-Dateien und die zugehörigen Datenmodelle verweist, liefert eine Beschreibung, die sich direkt am Code orientiert. In der Praxis funktioniert ein zweistufiges Vorgehen am besten: Im ersten Durchlauf erzeugt Claude Code ein strukturelles Gerüst mit allen Pfaden und Schemas, im zweiten Durchlauf werden gezielt Beschreibungstexte, Beispielwerte und Fehlerfälle ergänzt.

Projektspezifische Konventionen gehören in eine CLAUDE.md-Datei oder ein wiederverwendbares Prompt-Template, damit jede Generierung denselben Stil, dieselbe Sprache und dieselbe Struktur verwendet. Wichtig ist auch die Grenze zu kennen: Claude Code sieht nur, was im Code steht. Verhalten, das erst zur Laufzeit durch Plugins, Observer oder Extension Attributes entsteht, taucht in der generierten Beschreibung nicht automatisch auf, wenn diese Erweiterungen nicht ebenfalls Teil des gelesenen Kontexts sind.

4. REST- und GraphQL-Endpunkte gezielt dokumentieren lassen

REST- und GraphQL-APIs erfordern unterschiedliche Herangehensweisen bei der automatisierten Dokumentation. Bei REST-Endpunkten liefert webapi.xml bereits eine klare, deklarative Struktur, die sich fast eins zu eins in OpenAPI-Pfade übersetzen lässt. Bei GraphQL fehlt diese explizite Route-Deklaration: Die Struktur ergibt sich aus der schema.graphqls-Datei und den zugehörigen Resolver-Klassen, die tatsächlich bestimmen, welche Felder nullable sind, welche Fehler geworfen werden können und welche Berechtigungen geprüft werden.

Für GraphQL sollte Claude Code deshalb sowohl die Schema-Definition als auch die PHP-Resolver-Implementierung als Kontext bekommen. Ein Feld, das im Schema als nicht-nullable deklariert ist, aber im Resolver unter bestimmten Bedingungen null zurückgeben kann, ist ein klassisches Beispiel für eine Diskrepanz, die nur durch Lesen des Resolver-Codes auffällt. Die generierte Dokumentation sollte solche Fälle explizit als Anmerkung festhalten, damit Konsumenten der API wissen, dass die Schema-Deklaration allein nicht ausreicht, um das tatsächliche Verhalten zu verstehen.

{
  "paths": {
    "/V1/seosuite/redirects/{id}": {
      "get": {
        "summary": "Retrieve a single redirect rule by its ID",
        "operationId": "getRedirectById",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": {
            "description": "Redirect rule found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RedirectInterface" }
              }
            }
          },
          "404": {
            "description": "No redirect rule with the given ID exists"
          },
          "403": {
            "description": "Caller lacks the Mironsoft_SeoSuite::redirects ACL resource"
          }
        }
      }
    }
  }
}

5. Generierte Dokumentation gegen echtes API-Verhalten prüfen

Eine aus Code generierte Beschreibung ist nur so korrekt wie der gelesene Code selbst, und Code allein zeigt nicht immer das tatsächliche Laufzeitverhalten. Validierungsregeln, die in einer Basisklasse liegen, ACL-Prüfungen, die durch ein Plugin nachträglich verschärft wurden, oder Response-Felder, die ein Observer zur Laufzeit hinzufügt, sind im statischen Code oft nicht sichtbar. Deshalb reicht eine rein codebasierte Generierung nicht aus, um von einer verlässlichen Dokumentation zu sprechen.

Der zweite, unverzichtbare Schritt ist die Verifikation gegen eine laufende Staging-Umgebung. Ein einfacher Ansatz: reale Requests gegen die dokumentierten Endpunkte senden und die tatsächliche Antwortstruktur mit dem generierten Schema abgleichen. Abweichungen, etwa zusätzliche Felder, andere Pflichtfelder oder unerwartete Statuscodes, werden so sichtbar, bevor die Dokumentation veröffentlicht wird. Dieser Schritt sollte nicht manuell mit gelegentlichen curl-Aufrufen passieren, sondern als wiederholbares Skript, das bei jeder Änderung erneut laufen kann.

#!/usr/bin/env python3
"""Verify that live API responses match the generated OpenAPI schema."""
import sys
import requests
import yaml
from jsonschema import validate, ValidationError

with open("doc/openapi-draft.yaml") as f:
    spec = yaml.safe_load(f)

BASE_URL = "https://staging.mironsoft.de/rest/V1"

def check_endpoint(path: str, schema_ref: str, sample_id: int) -> bool:
    """Fetch a live endpoint and validate the response against the documented schema."""
    schema = spec["components"]["schemas"][schema_ref]
    response = requests.get(f"{BASE_URL}{path.format(id=sample_id)}", timeout=10)
    response.raise_for_status()
    try:
        validate(instance=response.json(), schema=schema)
        return True
    except ValidationError as exc:
        print(f"[MISMATCH] {path}: {exc.message}", file=sys.stderr)
        return False

if not check_endpoint("/seosuite/redirects/{id}", "RedirectInterface", sample_id=42):
    sys.exit(1)

print("[OK] Live response matches the documented schema")

6. Automatisierte Verifikation mit Contract Testing

Über einfache Schema-Vergleiche hinaus lohnt sich der Einsatz dedizierter Contract-Testing-Werkzeuge wie Schemathesis oder Dredd, die eine OpenAPI-Beschreibung als Vertrag nehmen und automatisch eine große Zahl von Testfällen dagegen generieren, inklusive Grenzwerten, fehlenden Pflichtfeldern und ungültigen Typen. Das deckt Fälle auf, an die man beim manuellen Testen selten denkt, etwa was passiert, wenn ein als Integer dokumentierter Parameter als negative Zahl oder als Zeichenkette übergeben wird.

Solche Tools laufen sinnvollerweise gegen eine dedizierte Staging-Instanz mit Testdaten, nicht gegen Produktion. Ergebnis ist ein Bericht, der jede Abweichung zwischen dokumentiertem Vertrag und tatsächlichem Verhalten auflistet: undokumentierte 500er-Fehler, Felder, die entgegen der Spezifikation fehlen, oder zusätzliche Felder, die die Dokumentation nicht erwähnt. Diese Berichte sind die eigentliche Grundlage dafür, der generierten Dokumentation zu vertrauen, nicht die Generierung selbst. Ohne diesen Schritt bleibt jede automatisiert erzeugte API-Beschreibung eine unbestätigte Behauptung über das System.

7. Dokumentation in den Entwicklungsworkflow integrieren

Der größte Fehler beim Einsatz von KI-gestützter Dokumentation ist, sie als einmalige Aktion zu behandeln: einmal generieren, einmal prüfen, dann vergessen. API-Dokumentation veraltet genauso schnell wie jede andere Doku, wenn sie nicht Teil des regulären Entwicklungszyklus ist. Der wirksamere Ansatz behandelt openapi-draft.yaml wie Quellcode: versioniert im Repository, mit Pull-Request-Review, und mit einer CI-Prüfung, die erkennt, wenn sich die API-Oberfläche geändert hat, die Dokumentation aber nicht mit aktualisiert wurde.

In der Praxis bedeutet das einen CI-Schritt, der bei jedem Pull Request prüft, ob Dateien unter Api/ oder etc/webapi.xml verändert wurden. Ist das der Fall, wird die Dokumentation neu generiert und mit der committeten Version verglichen. Weicht sie ab, schlägt der Check fehl, und ein Entwickler muss die Änderung bewusst prüfen und einchecken. Dieser Mechanismus verhindert, dass Dokumentation und Code auseinanderlaufen, ohne dass jemand aktiv daran denken muss, die Doku manuell zu aktualisieren.

#!/usr/bin/env bash
# ci-doc-check.sh - Run in every pull request that touches Api/ or webapi.xml
set -euo pipefail

CHANGED_FILES=$(git diff --name-only origin/main...HEAD)

if echo "$CHANGED_FILES" | grep -qE 'Api/.*Interface\.php|etc/webapi\.xml'; then
  echo "[INFO] API surface changed, regenerating documentation draft"
  bash generate-api-docs.sh
  git diff --exit-code doc/openapi-draft.yaml || {
    echo "[WARN] Documentation draft differs from committed version"
    echo "[WARN] Review doc/openapi-draft.yaml and commit the update"
    exit 1
  }
fi

Ergänzend lohnt sich ein Lint-Schritt, der die generierte OpenAPI-Datei vor dem Merge auf strukturelle Qualität prüft, unabhängig davon, ob der Inhalt inhaltlich korrekt ist. Ein Werkzeug wie Spectral erkennt fehlende Beschreibungen, inkonsistente Benennungen und verwaiste Schema-Referenzen, bevor ein Reviewer die Datei überhaupt öffnet.

// validate-openapi.js - Lint the generated OpenAPI draft before merging
import { Spectral } from "@stoplight/spectral-core";
import { oas } from "@stoplight/spectral-rulesets";
import fs from "node:fs";
import yaml from "js-yaml";

const spectral = new Spectral();
spectral.setRuleset(oas);

const draft = yaml.load(fs.readFileSync("doc/openapi-draft.yaml", "utf8"));

const results = await spectral.run(draft);
const errors = results.filter((r) => r.severity === 0);

if (errors.length > 0) {
  console.error(`[FAIL] ${errors.length} OpenAPI lint errors found`);
  errors.forEach((e) => console.error(`  ${e.path.join(".")}: ${e.message}`));
  process.exit(1);
}

console.log("[OK] Generated OpenAPI draft passes lint rules");

8. Grenzen und Risiken: Halluzinationen und veraltete Annahmen

KI-generierte API-Dokumentation ist kein risikofreier Prozess. Claude kann bei sparsam kommentierten Interfaces plausibel klingende, aber falsche Beschreibungen erzeugen, etwa ein Feld als "optional" bezeichnen, obwohl es in der Validierungslogik tatsächlich Pflicht ist. Bei älteren oder wenig verbreiteten Magento-Modulen mit dünner PHPDoc-Abdeckung steigt dieses Risiko deutlich, weil dem Modell schlicht weniger verlässliche Information zur Verfügung steht.

Ein zweites Risiko betrifft sicherheitsrelevante Felder: personenbezogene Daten, interne IDs oder Berechtigungsdetails sollten nie ungeprüft in eine öffentlich zugängliche Dokumentation übernommen werden, nur weil das Modell sie im Code gefunden hat. Ebenso wichtig: Das Modell kennt keine unternehmensspezifischen stillschweigenden Vereinbarungen, etwa dass ein bestimmter Endpunkt intern als deprecated gilt, obwohl der Code noch aktiv ist. Automatisiert generierte Dokumentation ersetzt daher nie die abschließende menschliche Prüfung vor Veröffentlichung, sie beschleunigt lediglich den Entwurfsprozess erheblich.

9. Werkzeuge und Ansätze im Vergleich

Es gibt mehrere etablierte Wege, API-Dokumentation zu erzeugen und zu pflegen, mit deutlichen Unterschieden bei Aufwand, Aktualität und Verlässlichkeit. Die folgende Tabelle stellt die gängigen Ansätze für Magento-Projekte gegenüber.

Der gemeinsame Nenner aller empfohlenen Praktiken in der Tabelle: Automatisierung beschleunigt die Erstellung, ersetzt aber nicht die Prüfung. Wer Claude Code als ersten Entwurfsschritt nutzt, Contract Testing als Verifikationsschicht einzieht und die Aktualität über CI erzwingt, bekommt eine Dokumentation, die tatsächlich dem Live-Verhalten der API entspricht statt nur dem Code-Stand zum Zeitpunkt der Generierung.

10. Zusammenfassung

Automatisiert generierte API-Dokumentation löst ein reales Problem: Manuell gepflegte Beschreibungen veralten zuverlässig, weil sie nicht Teil des eigentlichen Entwicklungsschritts sind. Claude Code kann aus webapi.xml, Service-Interfaces und Resolver-Klassen einen strukturierten ersten Entwurf ableiten, der deutlich schneller entsteht als eine manuelle Beschreibung. Entscheidend ist jedoch, dass dieser Entwurf niemals ungeprüft veröffentlicht wird.

Die eigentliche Verlässlichkeit entsteht erst durch Verifikation gegen echtes API-Verhalten, etwa mit Schema-Validierung realer Responses oder dediziertem Contract Testing, und durch Integration in einen wiederkehrenden Workflow statt eine Einmalaktion. Ein CI-Check, der bei jeder Änderung an der API-Oberfläche eine neue Dokumentation anstößt und Abweichungen sichtbar macht, verhindert, dass Code und Dokumentation erneut auseinanderdriften.

11. FAQ: API-Dokumentation automatisiert generieren