19 - Documentation : une API non documentee est une API inutile
Ce que tu vas apprendre
- Les outils de rendu : Swagger UI, Redoc, Scalar
- Comment écrire des code examples utiles
- La gestion de l'authentification dans la documentation
- Les stratégies pour garder la doc synchronisee avec le code
Prerequisites
Avoir lu l'article sur OpenAPI. Avoir un fichier OpenAPI 3.x a documenter.
J'ai deja utilise une API dont la seule documentation etait un message Slack du CTO : "les endpoints sont dans le fichier routes.ts, bonne chance". J'ai passe deux jours a lire le code source pour comprendre les paramètres attendus. Deux jours perdus parce que personne n'avait pris deux heures pour écrire une doc. Une API sans documentation, c'est comme un restaurant sans menu : tu peux probablement manger, mais personne ne sait ce qu'il va recevoir.
Swagger UI
Swagger UI est l'outil historique. Tu lui donnes un fichier OpenAPI et il généré une interface interactive ou le développeur peut tester les endpoints directement depuis le navigateur.
typescriptimport swaggerUi from "swagger-ui-express";
import spec from "./openapi.json";
app.use("/docs", swaggerUi.serve, swaggerUi.setup(spec, {
customSiteTitle: "Mon API - Documentation",
customCss: ".swagger-ui .topbar { display: none }"
}));
Les avantages : c'est interactif, les développeurs peuvent envoyer de vraies requêtes. L'inconvenient : l'interface est datee et la navigation dans une grosse spec est penible. Les schemas imbriques sont difficiles a suivre.
Redoc
Redoc prend la meme spec OpenAPI mais généré une documentation plus lisible, style référencé. Trois colonnes : navigation, description, exemples de code.
html<!DOCTYPE html>
<html>
<head>
<title>API Documentation</title>
</head>
<body>
<redoc spec-url="/openapi.json"></redoc>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>
Redoc est meilleur pour la lecture, Swagger UI est meilleur pour les tests. Beaucoup d'équipes utilisent les deux : Redoc comme documentation principale et Swagger UI comme playground.
Scalar
Scalar est le petit nouveau qui combine le meilleur des deux mondes. Interface moderne, code examples dans plusieurs langages, et un client de test intégré.
typescriptimport { apiReference } from "@scalar/express-api-reference";
app.use("/docs", apiReference({
spec: { url: "/openapi.json" },
theme: "default"
}));
Ce que j'aime chez Scalar : les code examples sont générés automatiquement en curl, JavaScript, Python, Go. Le développeur voit directement comment appeler l'endpoint dans son langage. C'est ce que j'utilise sur paltemps.fr pour la doc API.
Des code examples qui servent vraiment
Une doc sans exemples, c'est une recette sans les quantités. Pour chaque endpoint, montre :
- La requête complète (headers inclus)
- La réponse en cas de succes
- La réponse en cas d'erreur courante
yamlpaths:
/products:
post:
summary: Creer un produit
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/CreateProduct"
examples:
burger:
summary: Creer un burger
value:
name: "Burger classique"
price: 1200
category_id: 3
responses:
"201":
description: Produit cree
content:
application/json:
examples:
success:
value:
id: 42
name: "Burger classique"
price: 1200
created_at: "2026-03-29T10:00:00Z"
"422":
description: Validation echouee
content:
application/problem+json:
examples:
validation_error:
value:
type: "https://api.example.com/errors/validation-failed"
title: "Validation Failed"
status: 422
detail: "Le champ 'price' doit etre positif."
Authentification dans la doc
Ta doc doit expliquer clairement comment s'authentifier. OpenAPI supporte plusieurs schemas :
yamlcomponents:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: |
Envoie le header Authorization avec ton token JWT.
Pour obtenir un token, appelle POST /auth/login.
apiKey:
type: apiKey
in: header
name: X-API-Key
description: Cle API fournie lors de la creation de ton compte.
security:
- bearerAuth: []
Et dans Swagger UI ou Scalar, le développeur peut entrer son token et tester directement les endpoints proteges. Si tu ne configures pas ca, les gens vont tester avec curl en copiant les tokens a la main. Tu vas recevoir des tickets "l'API ne marche pas" alors que c'est juste un problème d'authentification.
Garder la doc synchronisee
Le plus gros defi, c'est que la doc derive du code. Trois stratégies :
1. Génération depuis le code (code-first)
Les frameworks comme Elysia, FastAPI ou NestJS generent la spec depuis les decorateurs. La doc ne peut pas deriver puisqu'elle EST le code.
2. Tests de contrat
Tu ecris des tests qui verifient que ton API respecte la spec OpenAPI :
typescriptimport { describe, it, expect } from "vitest";
describe("POST /products", () => {
it("respecte le schema OpenAPI", async () => {
const response = await app.request("/products", {
method: "POST",
body: JSON.stringify({ name: "Test", price: 100 }),
headers: { "Content-Type": "application/json" }
});
// Verifie que la reponse correspond au schema
const valid = validateAgainstSchema(await response.json(), "Product");
expect(valid).toBe(true);
});
});
3. Linting de la spec
redocly lint ou spectral lint verifient que ta spec est coherente, complète et suit les conventions :
bashnpx @redocly/cli lint openapi.yaml
Ca détecté les descriptions manquantes, les schemas non références, les exemples invalides. Mets-le dans ta CI.
La doc comme produit
Les meilleures API docs que j'ai vues (Stripe, Twilio, Vercel) traitent leur documentation comme un produit a part entière. Elles ont des guides "Getting Started", des tutorials par cas d'usage, des changelogs. La référencé OpenAPI n'est qu'une partie de la doc.
Pour une API interne, un bon README dans le repo avec les conventions d'équipe et un lien vers la doc Swagger suffit. Pour une API publique, investis dans des guides qui montrent les workflows complets, pas juste les endpoints individuels.
Résumé
- Swagger UI pour tester, Redoc pour lire, Scalar pour les deux
- Ajoute des examples complets (requête, succes, erreur) a chaque endpoint
- Configure l'authentification dans la spec pour que les devs testent sans friction
- Garde la doc synchronisee avec du code-first, des tests de contrat ou du linting
- Pour les API publiques, la référencé OpenAPI ne suffit pas : ajoute des guides
Article précédent : OpenAPI Article suivant : Testing