API-Dokumentation
Regeln
- OpenAPI 3.1-Spezifikation als einzige Quelle der Wahrheit – aus Code generieren, nicht manuell schreiben
- Zod-Schemata zu OpenAPI:
zod-openapi oder @asteasolutions/zod-to-openapi verwenden – einmal definieren, validieren und dokumentieren
- Interaktive Dokumentation: Scalar (modern, schnell) oder Swagger UI – unter
/docs oder /api-docs bereitstellen
- Jeder Endpunkt muss haben: Zusammenfassung, Beschreibung, Anfragekörperschema, alle Antwortcodes mit Beispielen
- Beispielanfrage/-antwort für jeden Endpunkt – realistische Daten verwenden, keine
"string"-Platzhalter
- Versionierungsstrategie: URL-Pfad (
/api/v1/, /api/v2/) für bahnbrechende Änderungen – einfacher als Header-Versionierung
- Fehlerantworten: alle Fehlerformen konsistent dokumentieren –
{ error: string, code: string, details?: object }
- Authentifizierung: Authentifizierungsschema (Bearer-Token, API-Key) im Abschnitt "Sicherheitsschemata" dokumentieren
- Endpunkte nach Ressource gruppieren:
/users, /products, /orders – Tags für die Gruppierung in der Dokumentationsoberfläche verwenden
Muster
import { z } from "zod";
import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
extendZodWithOpenApi(z);
const UserSchema = z.object({
id: z.string().uuid().openapi({ example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }),
name: z.string().openapi({ example: "Jane Smith" }),
email: z.string().email().openapi({ example: "[email protected]" }),
}).openapi("User");
const CreateUserSchema = UserSchema.omit({ id: true }).openapi("CreateUser");
registry.registerPath({
method: "post",
path: "/api/v1/users",
summary: "Einen Benutzer erstellen",
request: { body: { content: { "application/json": { schema: CreateUserSchema } } } },
responses: {
201: { description: "Benutzer erstellt", content: { "application/json": { schema: UserSchema } } },
400: { description: "Validierungsfehler" },
},
});
Vermeiden
- OpenAPI-YAML von Hand schreiben – aus Zod-Schemata oder Routendefinitionen generieren
- Fehlende Fehlerantwortdokumentation – 400, 401, 403, 404, 500 dokumentieren
- Generische Beispiele wie
"string" oder 0 – verwenden Sie realistische Werte, die die Form echter Daten zeigen
- Dokumentation, die von der Implementierung abweicht – Spezifikation aus denselben Schemata generieren, die für die Validierung verwendet werden