Documentation d'API avec des exemples exécutés en intégration continue

Objectif

Une documentation dont les exemples ne peuvent pas dériver par rapport à l'API, parce que les mêmes fichiers d'exemples sont validés, exécutés et rendus.

Prérequis

Un document OpenAPI faisant office de contrat ; un bac à sable ou un serveur de test avec des données d'amorçage stables ; un pipeline d'intégration continue dans le dépôt de l'API. La spécification OpenAPI 3.1 (citée) définit les objets Example avec soit une value, soit une externalValue, s'attend à ce que chaque exemple soit compatible avec son schéma, et indique que l'outillage peut valider cette compatibilité automatiquement et rejeter les exemples incompatibles. Le module doctest de Python (cité) illustre l'idée sous-jacente : un texte qui ressemble à une session interactive est exécuté et vérifié pour fonctionner exactement comme indiqué ; rustdoc (cité) exécute de même les exemples de documentation comme des tests.

Étapes

1. Écrire un exemple par opération et par erreur documentée, sous forme de fichiers référencés depuis le document OpenAPI via externalValue, ou comme entrées examples nommées ; nommer chacun d'après son scénario (create-order-missing-address).
2. Valider chaque exemple par rapport à son schéma de requête ou de réponse en intégration continue ; faire échouer la construction en cas de non-conformité.
3. Exécuter les exemples de requêtes contre le bac à sable en intégration continue. Comparer la réponse réelle à l'exemple de réponse documenté, en ignorant les champs déclarés volatils (identifiants, horodatages) et en faisant échouer la vérification sur tout le reste.
4. Générer la documentation à partir des mêmes fichiers : les pages de référence, le guide de démarrage rapide et les extraits de SDK incluent les fichiers d'exemples au lieu de copies collées.
5. Pour les échantillons de code en plusieurs langages, les générer à partir des exemples avec un modèle par langage et exécuter chacun contre le bac à sable ; un échantillon qui n'est pas exécuté n'est qu'une copie collée et finira par dériver.
6. Lorsqu'un exemple échoue après un changement d'API, trancher explicitement : soit le changement est un bogue, soit l'exemple et le texte changent dans le même commit que l'API.
7. Afficher sur la page de documentation la date de vérification en intégration continue, afin que les lecteurs puissent distinguer une page maintenue d'une page obsolète.

Résultat attendu

Chaque exemple du site s'est exécuté contre un serveur réel depuis le dernier changement d'API ; lecteurs et agents peuvent copier une requête et recevoir la réponse documentée.

Limites et base de vérification

Les exemples n'exercent que les chemins documentés et ne constituent pas une suite de tests. Les données d'amorçage du bac à sable doivent être stables, sinon l'étape de comparaison devient du bruit. Le protocole est proposé ; aucune réduction des défauts de documentation n'est affirmée.