Ein Schema beantwortet eine bestimmte Art von Frage
OpenAPI beschreibt Operations, Parameter, Request- und Response-Strukturen, Status Codes und wiederverwendbare Schemas sehr gut. Deshalb eignet es sich als Quelle für generierte Reference und automatische Validierung.
Problematisch wird es, wenn ein vollständiges Schema mit vollständiger Developer Documentation gleichgesetzt wird.
Developers brauchen eine Journey
Neue Nutzer fragen zuerst: Wie authentifiziere ich mich? Welche Umgebung verwende ich? Was ist der kleinste erfolgreiche Request? Wie hängen Ressourcen zusammen? Wie funktionieren Retries? Solche Antworten gehören in konzeptionelle und task-orientierte Inhalte, die mit der Reference verbunden sind.
Beispiele transportieren Semantik
Ein Schema kann sagen, dass ein Feld ein String ist. Ein gutes Beispiel zeigt realistische Werte, Zusammenhänge und typische Responses. Teste Examples soweit möglich und halte sie nah genug am Contract, damit Änderungen im Review sichtbar werden.
Dokumentiere Fehler als normalen Pfad
Generierte Reference listet Errors oft nur auf. Erkläre, welche Fehler retrybar sind, welche einen ungültigen Zustand anzeigen, wie Rate Limits kommuniziert werden und welche IDs Support benötigt.
Erfinde keine Garantien. Unklare Idempotency oder Retry-Semantik ist eine Produktfrage.
Nutze OpenAPI für seine Stärke
Generiere Field Facts und Strukturen aus der Specification und validiere Examples. Verwende redaktionelle Arbeit für mentale Modelle, Workflows, Trade-offs und Recovery.
Gute API-Dokumentation behandelt das Schema als Evidenz und die veröffentlichte Website als Developer Experience rund um diese Evidenz.
Praxisbeispiel
Mach aus „OpenAPI ist eine Wahrheitsquelle, aber nicht die gesamte API-Dokumentation“ eine vollständige Entwickleraufgabe. Verwende eine fiktive, aber realistische Ressource wie Bericht, Gerät oder Bestellung und beschreibe den kürzesten Weg von der Authentifizierung zum erfolgreichen Ergebnis. Zeige Request, wichtige Response-Felder, einen wahrscheinlichen Fehler und die nächste Aktion danach.
Prüfe das Beispiel wie beim Bau eines Clients:
- welche Werte ersetzt werden müssen;
- welche IDs der Server zurückgibt und später wiederverwendet werden;
- welcher Status oder welches Feld Erfolg bestätigt;
- was bei falschen Credentials, Eingaben oder Limits zu tun ist.
API-Dokumentation ist stark, wenn Entwickler die Interaktion vorhersagen können und nicht nur Endpoint-Namen wiedererkennen.
Kurzer Redaktionscheck
- Ein Schema beantwortet eine bestimmte Art von Frage. OpenAPI beschreibt Operations, Parameter, Request- und Response-Strukturen, Status Codes und wiederverwendbare Schemas sehr gut.
- Developers brauchen eine Journey. Neue Nutzer fragen zuerst: Wie authentifiziere ich mich?
- Beispiele transportieren Semantik. Ein Schema kann sagen, dass ein Feld ein String ist.
- Dokumentiere Fehler als normalen Pfad. Generierte Reference listet Errors oft nur auf.
