Un schema répond à une catégorie précise de questions
OpenAPI décrit très bien operations, paramètres, structures de request/response, status codes et schemas réutilisables. C’est donc une excellente source pour une reference générée et la validation automatique.
Le problème commence quand une équipe suppose qu’un schema complet produit automatiquement une documentation complète.
Le developer a besoin d’un parcours
Avant de regarder chaque champ, un nouvel utilisateur veut savoir comment s’authentifier, quel environnement utiliser, quelle est la requête minimale, comment les ressources se relient et comment fonctionnent les retries. Ces réponses appartiennent au contenu conceptuel et orienté tâche, relié à la référence.
Les exemples portent la sémantique
Un schema peut dire qu’un champ accepte une string. Un bon exemple montre une valeur réaliste, l’interaction entre les champs et une réponse typique. Testez les exemples quand c’est possible et gardez-les assez proches du contract pour que les changements soient visibles en review.
Documentez l’échec comme un chemin normal
La reference générée liste souvent les errors sans expliquer la récupération. Indiquez lesquels peuvent être retry, lesquels signifient un état invalide, comment les rate limits sont communiqués et quels identifiers sont utiles au support.
N’inventez pas de garanties. Une idempotency ou un retry mal défini est une question produit.
Laissez OpenAPI faire ce qu’il fait bien
Générez les faits de champ et la structure depuis la specification, puis validez les exemples. Réservez le travail éditorial aux modèles mentaux, workflows, trade-offs et recovery.
Une bonne documentation traite le schema comme une preuve et le site publié comme une expérience construite autour de cette preuve.
Exemple pratique
Transformez « OpenAPI est une source de vérité, pas toute la documentation d’’API » en une tâche développeur complète. Utilisez une ressource fictive mais réaliste — rapport, appareil ou commande — et décrivez le chemin le plus court de l’authentification au résultat réussi. Incluez la requête, les champs importants de la réponse, une erreur probable et l’action suivante.
Relisez l’exemple comme si vous construisiez réellement un client : Pour « OpenAPI est une source de vérité, pas toute la documentation d’’API », gardez le test centré sur la décision précise proposée par l’article.
- quelles valeurs doivent être remplacées ;
- quels identifiants sont renvoyés puis réutilisés ;
- quel statut ou champ confirme le succès ;
- que faire en cas de credentials, données ou limites incorrects.
- Pour « OpenAPI est une source de vérité, pas toute la documentation d’’API », définissez avant de commencer un critère observable de réussite ou d’échec.
Une bonne documentation API permet de prévoir l’interaction avec le système, pas seulement de reconnaître les noms d’endpoints. L’exercice vérifie ainsi précisément « OpenAPI est une source de vérité, pas toute la documentation d’’API » au lieu de devenir un audit documentaire générique.
Checklist éditorial rapide
- Un schema répond à une catégorie précise de questions. OpenAPI décrit très bien operations, paramètres, structures de request/response, status codes et schemas réutilisables.
- Le developer a besoin d’un parcours. Avant de regarder chaque champ, un nouvel utilisateur veut savoir comment s’authentifier, quel environnement utiliser, quelle est la requête minimale, comment les ressources se relient et comment fonctionnent les retries.
- Les exemples portent la sémantique. Un schema peut dire qu’un champ accepte une string.
- Documentez l’échec comme un chemin normal. La reference générée liste souvent les errors sans expliquer la récupération.
