Une bonne documentation est un élément clef pour garantir l’adoption et l’efficacité de vos API.

Dans ce chapitre, nous présentons les bonnes pratiques pour produire des documents complets, à jour et faciles à comprendre, afin de faciliter la vie des développeurs et d’assurer la cohérence entre vos API.

- Règles DOC -

DOC‑01 : Les Spécifications Open API DOIVENT être utilisées.

DOC‑02 : La version des Spécifications Open API DEVRAIT être v3.x.x ou supérieure.

DOC‑03 : La version des Spécifications Open API PEUT être v2.x (exception).

DOC‑04 : La version v1.x de la Spécification Open API NE DOIT PAS être utilisée.

DOC‑05 : La Spécification Open API DOIT être rédigée en langue anglaise.

DOC‑06 : La Spécification Open API PEUT être exposée dans plusieurs langues.

DOC‑07 : La documentation de l’API DEVRAIT inclure une collection de requêtes (Postman, Bruno, Insomnia, etc.) ainsi qu’un fichier d’environnement associé.