Documentation d'API
Règles
- Spécification OpenAPI 3.1 comme source unique de vérité — générée à partir du code, pas écrite manuellement
- Schémas Zod vers OpenAPI : utiliser
zod-openapi ou @asteasolutions/zod-to-openapi — définir une fois, valider et documenter
- Documentation interactive : Scalar (moderne, rapide) ou Swagger UI — servir sur
/docs ou /api-docs
- Chaque point d'accès doit avoir : un résumé, une description, un schéma du corps de la requête, tous les codes de réponse avec des exemples
- Exemple de requête/réponse pour chaque point d'accès — utiliser des données réalistes, pas des espaces réservés
"string"
- Stratégie de versionnage : chemin d'URL (
/api/v1/, /api/v2/) pour les changements cassants — plus simple que le versionnage par en-tête
- Réponses d'erreur : documenter tous les formats d'erreur de manière cohérente —
{ error: string, code: string, details?: objet }
- Authentification : documenter le schéma d'authentification (jeton Bearer, clé API) dans la section des schémas de sécurité
- Grouper les points d'accès par ressource :
/users, /products, /orders — utiliser des balises (tags) pour le regroupement dans l'interface de documentation
Exemples
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/utilisateurs",
summary: "Créer un utilisateur",
request: { body: { content: { "application/json": { schema: CreateUserSchema } } } },
responses: {
201: { description: "Utilisateur créé", content: { "application/json": { schema: UserSchema } } },
400: { description: "Erreur de validation" },
},
});
À éviter
- Écrire du YAML OpenAPI à la main — générer à partir de schémas Zod ou de définitions de routes
- Omettre la documentation des réponses d'erreur — documenter les codes 400, 401, 403, 404, 500
- Exemples génériques comme
"string" ou 0 — utiliser des valeurs réalistes qui montrent la forme des données réelles
- Documentation qui s'écarte de l'implémentation — générer la spécification à partir des mêmes schémas utilisés pour la validation