Checklist de documentation OpenAPI

Contrat comme source unique de vérité

Je garde la description OpenAPI dans le même référentiel que le code du service. Cela rend le fichier visible à quiconque lit le code source et permet au contrôle de version de montrer chaque modification.

Emplacement du fichier

Je place le fichier à docs/openapi.yaml à la racine du référentiel. Le chemin est court, facile à trouver et ne rentre pas en conflit avec les ressources générées.

Pratiques de contrôle de version

Chaque modification apportée au contrat d'API passe par une demande d'extraction. J'exige au moins un approbateur qui vérifie que la description correspond aux modifications de code. Je fais également fonctionner une étape de lint dans le pipeline CI avant que la PR puisse être fusionnée.

Éviter les écarts avec les tests de contrat

J'ajoute une suite de tests qui appelle le service en cours d'exécution et valide chaque réponse par rapport au schéma OpenAPI. Si le service renvoie quelque chose qui ne correspond pas au contrat, le test échoue et l'équipe reçoit un feedback immédiat.

- Le contrat vit à côté du code, pas dans un wiki séparé - Les examens de demande d'extraction détectent les discordances précocement - Les tests automatisés protègent contre la dérive à l'exécution - L'historique montre qui a modifié quoi et pourquoi

Documentation des erreurs

Les intégrateurs remarquent d'abord les problèmes lorsqu'ils reçoivent une erreur qu'ils n'attendaient pas. La description des formes 4xx et 5xx réduit les tickets de support et permet aux générateurs de clients de produire du code de gestion des erreurs correct.

Définition des formes 4xx

J'ajoute une section components.responses pour chaque erreur client que l'API peut renvoyer. Les entrées typiques incluent 400 Bad Request pour les problèmes de validation, 401 Unauthorized pour les informations d'identification manquantes ou invalides, 403 Forbidden pour les scopes insuffisants et 422 Unprocessable Entity pour les violations des règles métier.

Définition des formes 5xx

Les erreurs du serveur sont moins fréquentes, mais nécessitent néanmoins une documentation. Je décris une réponse générique 500 Internal Server Error et, le cas échéant, une réponse 503 Service Unavailable avec un en-tête Retry-After.

Exemple de réponse d'erreur

- Documenter chaque code d'erreur distinct que le service peut émettre - Fournir un message court et un tableau de détails facultatif - Conserver les schémas d'erreurs réutilisables sur plusieurs points de terminaison - Mettre à jour les documents d'erreur lorsque vous ajoutez de nouvelles règles de validation

Exemples à côté des schémas

Lorsqu'un développeur voit un exemple de requête ou de réponse clair, le temps passé à deviner diminue de manière spectaculaire. Je place les exemples directement à côté du schéma qu'ils illustrent, en utilisant les champs example ou examples d'OpenAPI.

Exemples intégrés

Pour les objets simples, j'ajoute une valeur d'exemple à l'intérieur du schéma. Cela apparaît dans Swagger UI et Redoc sans fichiers supplémentaires.

Exemples externes

Pour les charges utiles plus importantes, je garde un dossier examples/ séparé et je le référence avec $ref:./examples/payment-request.json. Cela permet de garder le fichier principal lisible tout en fournissant des échantillons riches.

Génération d'extraits de code

APIDocGen lit le fichier OpenAPI et crée des extraits de code curl, JavaScript fetch et Python requests pour chaque opération. Je stocke ces extraits dans le répertoire docs/snippets/ et je les relie à la description de l'opération.

- Les exemples réduisent les allers-retours sur Slack ou par e-mail - Les exemples intégrés conviennent bien pour les petits DTO - Les fichiers externes maintiennent la spécification principale propre - Les extraits de code générés donnent aux développeurs un point de départ pour copier-coller

Lint dans CI

Une référence cassée ou une opérationId manquante peut silencieusement casser les générateurs de clients et les sites de documentation. J'exécute un linter dans le cadre du pipeline de construction et je fais échouer la construction en cas d'erreur.

Choisir un linter

J'utilise Spectral avec le jeu de règles spectral:oas car il comprend OpenAPI 3.1 et me permet d'ajouter des règles personnalisées pour nos conventions internes.

Étapes d'intégration CI

Dans le workflow GitHub Actions, j'ajoute une étape qui installe Spectral via npm, puis exécute spectral lint docs/openapi.yaml. L'étape utilise le paramètre continue-on-error: false afin que tout problème arrête le pipeline.

Gestion de $ref et operationId

Le linter vérifie que chaque $ref peut être résolu et que chaque operationId est unique dans le fichier. Je force également que tous les chemins aient un summary et une description.

Règle | Sévérité | Ce qu'elle vérifie no-unresolved-ref | erreur | Tous les pointeurs $ref doivent être résolus operation-operationId | erreur | Chaque opération doit avoir une operationId no-duplicate-operationId | erreur | Les valeurs operationId doivent être uniques path-summary | avertissement | Chaque élément de chemin nécessite un résumé path-description | avertissement | Chaque élément de chemin nécessite une description

- L'étape de lint s'exécute sur chaque push et demande de tirage - Les erreurs bloquent les fusions, les avertissements apparaissent dans la sortie de vérification - Les règles personnalisées peuvent imposer des conventions d'appellation spécifiques à l'entreprise - La sortie est facile à lire dans l'interface utilisateur des vérifications GitHub

Ce que cela n'est pas

Je veux être honnête sur les limites d'une liste de contrôle. Suivre ces éléments améliore la qualité de votre description OpenAPI, mais cela ne garantit pas une documentation parfaite dans toutes les situations.

Pas de garantie de documentation parfaite

Même avec un fichier propre et des exemples riches, les développeurs peuvent encore trouver des lacunes si le comportement de l'API change à l'exécution. La liste de contrôle vous aide à détecter de nombreux problèmes, mais vous devez encore vérifier le service en direct.

Pas de remplacement pour les tests à l'exécution

Les tests de contrat qui valident les réponses contre le schéma sont précieux, mais ils ne remplacent pas les tests d'exploration, les tests de performance ou les analyses de sécurité. Traitez la liste de contrôle comme une couche de défense.

Pas de substitut à une bonne conception

Si l'API sous-jacente est confuse ou incohérente, aucune quantité de documentation ne la rendra facile à utiliser. Consacrez du temps à la modélisation de ressources propres, à la dénomination claire et aux codes d'erreur sensés avant d'investir lourdement dans la documentation.

- La liste de contrôle améliore la cohérence, pas la correction de la logique métier - La surveillance à l'exécution est toujours nécessaire pour détecter les dérives après le déploiement - Une bonne conception réduit la quantité de texte explicatif requise - Traitez la documentation comme un artefact vivant, et non comme une tâche ponctuelle

Garder les documents à jour

Un fichier OpenAPI peut devenir obsolète si personne ne remarque que le code a divergé. J'ai mis en place des habitudes légères qui rendent les fichiers obsolètes visibles avant qu'ils ne causent de confusion.

Génération automatisée

Je configure le pipeline CI pour régénérer la documentation HTML (en utilisant Redoc) après chaque build réussi et publie la sortie sur un hôte de site statique. L'URL des documents publiés apparaît dans le commentaire de la demande d'extraction, afin que les réviseurs puissent voir la version rendue instantanément.

Processus d'examen

Chaque fois qu'un contributeur modifie un gestionnaire ou un modèle de données, je lui demande d'ouvrir le fichier OpenAPI et de vérifier que les chemins, les paramètres et les réponses pertinents reflètent le changement. J'ajoute un commentaire de rappel dans le modèle de demande d'extraction.

Surveillance des fichiers obsolètes

Je lance un travail nocturne qui git-diff le fichier OpenAPI par rapport à la version de la semaine précédente. Si la diff montre plus de trente lignes modifiées, le travail publie un message sur le canal d'équipe demandant un examen rapide.

- Les documents publiés donnent un indice visuel que la source est actuelle - Les rappels d'examen maintiennent le contrat proche du code - La diff automatisée met en évidence les éditions importantes et non intentionnelles - Toutes les étapes s'exécutent sans intervention manuelle

Liste de contrôle de l'opérateur pour la documentation OpenAPI (2026)

Je garde une liste de contrôle écrite à côté de chaque version qui touche ce sujet. La liste est volontairement ennuyeuse : nommer le propriétaire, nommer l'artefact de preuve, et nommer la procédure de restauration. Si une étape ne peut pas produire un fichier, un ticket ou une ligne de journal, ce n'est pas une étape - c'est un vœu.

Avant de modifier la production

- Geler la branche ou la révision de configuration que vous allez mesurer. - Enregistrer le mode d'échec actuel avec une entrée concrète et une sortie concrète. - Confirmer l'identité sous laquelle le travail s'exécute, et si cette identité peut accéder à des données qu'elle ne devrait pas. - Ouvrir les références principales que vous allez citer : https://learn.openapis.org/best-practices.html, https://redocly.com/docs/redoc.

Pendant que vous exécutez la vérification

- Préférer un chemin reproductible à dix captures d'écran anecdotiques. - Écrire le résultat attendu en toute sécurité avant de déclencher l'outil ou la requête. - Capturer la commande exacte, l'invite, le schéma ou l'expression régulière sous test - et non une paraphrase. - Si le système peut agir (envoyer, écrire, supprimer, transférer), exiger une limite de confirmation dans le même passage.

Après avoir terminé

- Enregistrer le risque résiduel avec un propriétaire et une date, même lorsque l'analyse est propre. - Ne pas convertir un contrôle vert en langage de vente qui prétend à l'exhaustivité. - Réexécuter la même liste de contrôle lorsque le modèle, le schéma de l'outil ou les règles de validation changent.

Signal | Qu'enregistrer | Arrêter l'expédition? Écriture ou envoi inattendu | Nom de l'outil, arguments, identité | Oui jusqu'à ce que cela soit bloqué Action destructive sans confirmation | Chemin d'appel et contournement | Oui Texte non fiable traité comme instruction | Surface source et action résultante | Oui pour la portée de l'agent Analyseur propre, jugement ouvert | Éléments différés + propriétaire | Seulement si le chemin principal est sécurisé

api-docgen aide pour le premier passage mesurable. Les choix d'architecture, la validation légale et les allégations à destination des clients nécessitent toujours un propriétaire humain. Traitez chaque ligne de la liste de contrôle comme un support de décision, et non comme un certificat.

Comment j'explique les limites aux acheteurs

Lorsqu'un prospect me demande si le produit "couvre tout", je réponds avec la limite : les vérifications automatisées détectent les modèles connus ; les chaînes nouvelles et le jugement politique nécessitent toujours un examen. Cette honnêteté permet de réduire la charge de support et de garder le blog aligné sur ce que le produit fait réellement.

Si vous avez besoin d'un second avis, associez ce texte aux références ci-dessous et à votre propre reproduction de staging. Ne sautez pas l'étape de reproduction simplement parce qu'un modèle a rédigé un résumé confiant.

Références

- https://learn.openapis.org/best-practices.html - https://redocly.com/docs/redoc - https://spec.openapis.org/oas/latest.html - https://spec.openapis.org/oas/latest.html#schema-object