Documentation API OpenAPI : versionner et documenter (guide)

Pourquoi la documentation API OpenAPI change la donne pour une PME

Une API est la porte d'entrée de votre logiciel pour les autres programmes. Votre site e-commerce en parle avec votre ERP, votre application mobile avec votre serveur, votre outil de réservation avec l'agenda d'un partenaire. Si personne ne sait exactement ce que cette porte accepte et renvoie, chaque branchement devient un chantier.

La documentation sert à éviter ces chantiers. Elle dit quelles adresses existent, quelles données envoyer, quelles réponses attendre et quelles erreurs gérer. Quand elle est fiable, un développeur externe peut intégrer votre service sans vous appeler. Quand elle est fausse ou absente, il devine, et il se trompe.

Pour un dirigeant, l'enjeu est simple : moins d'heures facturées en allers-retours, moins de dépendance à une seule personne qui « sait comment ça marche », et une API que vous pouvez ouvrir à des partenaires sans craindre l'incident. C'est là qu'intervient OpenAPI.

OpenAPI et Swagger : qui est qui ?

Les deux noms sont souvent confondus. À l'origine, Swagger était à la fois un format de description et une suite d'outils. En 2016, le format a été confié à une fondation neutre, l'OpenAPI Initiative, et rebaptisé. Son texte officiel s'intitule d'ailleurs « The OpenAPI Specification ».

Aujourd'hui, on parle donc de l'OpenAPI Specification pour le format, et de Swagger pour une famille d'outils qui l'exploitent : Swagger UI pour afficher la documentation, Swagger Editor pour la rédiger, Swagger Codegen pour générer du code. D'autres outils, libres ou commerciaux, lisent le même format. C'est tout l'intérêt d'un standard : vous n'êtes pas enfermé chez un éditeur.

Ce que contient un openapi document

Un openapi document est un fichier texte, écrit en YAML ou en JSON. Le YAML est plus agréable à lire et à écrire à la main, le JSON plus courant pour les échanges entre programmes. Les deux décrivent exactement la même chose.

Ce fichier regroupe plusieurs blocs. Le bloc info donne le titre, la version et la description de l'API. Le bloc servers liste les adresses où elle tourne, par exemple production et préproduction. Le bloc paths décrit chaque endpoint, c'est-à-dire chaque adresse et chaque méthode HTTP disponible. Enfin, le bloc components stocke les éléments réutilisables : schémas de données, paramètres communs, réponses d'erreur, méthodes d'authentification.

Documenter une API avec OpenAPI : les étapes dans l'ordre

Documenter an API with OpenAPI ne commence pas par l'ouverture d'un éditeur. On commence par savoir ce que fait l'API, pour qui, et comment elle va vivre. Voici l'ordre qui évite de refaire le travail deux fois.

Étape 1 : faire l'inventaire de l'existant

Listez tous les endpoints en place, avec leur méthode, leurs paramètres et leurs réponses réelles. Sur une API déjà en production, les journaux du serveur et le code source sont vos meilleures sources. Ne vous fiez pas à la mémoire de l'équipe : on découvre presque toujours des adresses oubliées ou des champs que personne n'utilise plus.

Notez aussi qui consomme l'API. Une application interne, trois partenaires, un public de développeurs inconnus ? La réponse change le niveau de détail attendu et la prudence à avoir lors des futures versions.

Étape 2 : choisir entre design-first et code-first

Deux approches coexistent. En design-first, on écrit d'abord le contrat OpenAPI, on le valide avec les personnes concernées, puis on code. En code-first, on annote le code et un outil génère le fichier à partir de lui.

Le design-first convient bien aux nouvelles API et aux projets où plusieurs équipes travaillent en parallèle : le front peut avancer sur des données simulées pendant que le back se construit. Le code-first est souvent plus réaliste pour documenter une API qui existe déjà. Beaucoup de projets mélangent les deux : génération initiale depuis le code, puis le fichier devient la référence et on le maintient avec soin.

Étape 3 : remplir les informations générales

Commencez par le bloc info. Le titre doit être clair, la version doit suivre une règle définie (on y revient plus bas), et la description doit expliquer en quelques lignes à quoi sert l'API. Ajoutez un contact technique et, si l'API est ouverte à des tiers, une licence et un lien vers les conditions d'utilisation.

Déclarez ensuite les serveurs. Indiquez l'adresse de production et celle de l'environnement de préproduction, chacune avec une courte description. Le lecteur doit savoir immédiatement où tester sans risque et où se trouvent les vraies données.

Étape 4 : décrire chaque endpoint, ses paramètres et ses réponses

C'est le cœur du travail. Pour chaque endpoint, rédigez un résumé court et une description qui explique le comportement réel, y compris les cas limites. Un résumé du type « Récupère une commande » ne suffit pas si l'endpoint ne renvoie que les commandes de l'utilisateur connecté : dites-le.

Chaque parameter doit être décrit avec son emplacement (chemin, requête, en-tête ou cookie), son type, son caractère obligatoire ou non, et une valeur d'exemple. Pour le corps de la requête, on précise le type de contenu, le plus souvent application/json, et le schéma attendu.

Côté réponses, documentez tous les cas, pas seulement le succès. Un endpoint de création renvoie en général un 201, mais aussi un 400 si les données sont invalides, un 401 si l'authentification manque, un 409 en cas de doublon. Si vous hésitez sur le sens d'un code, notre page sur les codes de réponse HTTP fait le point. Pour chaque response, indiquez le schéma du corps renvoyé et un exemple.

Étape 5 : factoriser les schémas dans components

Un client, une commande, une adresse apparaissent dans plusieurs endpoints. Plutôt que de recopier leur structure à chaque fois, on la définit une seule fois dans components, puis on y fait référence. Si un champ change, vous le modifiez à un seul endroit.

Un schéma décrit un objet : ses propriétés, leur type, leur format, les champs obligatoires et les valeurs possibles. Depuis la version 3.1, la syntaxe est alignée sur JSON Schema, ce qui permet de réutiliser des validateurs standard. Concrètement, dans le fichier, sous content puis application/json, la clé schema pointe vers l'objet défini dans components : c'est ce lien json: schema qui permet aux outils de valider automatiquement les échanges.

Étape 6 : ajouter des exemples réalistes

Les exemples sont souvent la partie la plus lue d'une documentation. Un développeur regarde d'abord un example de requête et de réponse, puis remonte vers le schéma s'il a besoin de détails. Soignez-les : des valeurs plausibles, cohérentes entre elles, qui passent la validation du schéma.

Utilisez des données fictives. Jamais de vrais noms de clients, de vraies adresses e-mail ou de vrais numéros de téléphone. Un exemple copié depuis la base de production est une fuite de données personnelles, même s'il paraît anodin.

Étape 7 : publier la documentation

Une fois le fichier valide, il faut le rendre lisible. Swagger UI transforme le fichier en page web interactive : chaque endpoint s'affiche avec ses paramètres, et un bouton « Try it out » permet d'envoyer une vraie requête depuis le navigateur. D'autres outils comme Redoc proposent une mise en page en trois colonnes, plus proche d'une documentation éditoriale.

Décidez qui doit y accéder. Une API interne peut avoir une documentation protégée par mot de passe. Une API publique gagne à être documentée sur une adresse ouverte. Dans les deux cas, désactivez l'essai en direct sur la production si vous ne voulez pas que n'importe qui crée de vraies données en cliquant.

Versionner une API sans casser les intégrations

Une API vit. On ajoute des fonctions, on corrige des erreurs, on renomme un champ mal choisi. Le problème, c'est que chaque client a codé son intégration à partir de ce que l'API faisait au moment où il l'a branchée. Versionner, c'est faire évoluer l'API tout en laissant à chacun le temps de suivre.

Deux versions à ne pas confondre

Dans un fichier OpenAPI, deux numéros coexistent. Le premier, en tête du fichier, indique la version du format utilisé, par exemple 3.1.0. Il dit aux outils comment lire le fichier. Le second, dans le bloc info, est la version de votre API à vous. C'est lui qui compte pour vos clients.

Changer la version du format ne change rien pour les consommateurs de l'API. Changer la version de l'API, en revanche, doit avoir un sens précis et suivre une règle connue de tous.

Changements compatibles et changements cassants

Tout ne mérite pas une nouvelle version majeure. La question à se poser est simple : un client qui ne change rien à son code va-t-il continuer à fonctionner ? Si oui, le changement est compatible. Si non, il est cassant.

Une convention répandue s'inspire du versionnage sémantique : un numéro majeur pour les changements cassants, un mineur pour les ajouts compatibles, un correctif pour les corrections sans effet sur le contrat. Elle n'est pas obligatoire, mais elle a le mérite d'être comprise par la plupart des développeurs.

Où placer le numéro de version

Pour que les clients choisissent la version qu'ils appellent, plusieurs méthodes existent. Aucune n'est parfaite ; l'important est d'en choisir une et de s'y tenir.

Pour une PME qui démarre, la version dans l'adresse reste souvent le choix le plus lisible. Dans OpenAPI, elle se déclare naturellement dans l'adresse du serveur ou dans les chemins. Chaque version majeure peut alors avoir son propre fichier, ce qui garde la documentation claire.

Annoncer les dépréciations

On ne coupe pas une ancienne version du jour au lendemain. La spécification permet de marquer un endpoint, un paramètre ou un champ comme déprécié avec l'attribut deprecated. Swagger UI l'affiche alors barré ou signalé, et les développeurs voient qu'il faut migrer.

Complétez ce marquage par une vraie communication : une page de journal des modifications, un e-mail aux partenaires connus, une date de fin annoncée à l'avance. La durée de coexistence dépend de vos clients. Un partenaire qui publie une application mobile a besoin de plus de temps qu'une équipe interne qui déploie chaque semaine.

Versionner le fichier lui-même avec Git

Le fichier OpenAPI est du texte : il se range parfaitement dans Git, à côté du code. Chaque modification laisse une trace, avec son auteur, sa date et sa raison. On peut comparer deux versions du contrat, revenir en arrière, et relire les changements avant de les accepter.

Faites passer chaque évolution du fichier par une relecture, comme pour le code. C'est le moment où quelqu'un repère qu'un champ a été renommé par erreur ou qu'un exemple ne correspond plus au schéma. Une étiquette Git par version publiée permet aussi de retrouver exactement le contrat que tel partenaire a utilisé à telle date.

Les outils pour écrire, vérifier et automatiser

L'écosystème est riche. Plutôt qu'une liste de produits, voici les familles de tools utiles et ce qu'elles apportent. Choisissez-les selon votre équipe et vos habitudes, pas selon la mode.

Éditer et valider le fichier

Un éditeur qui comprend OpenAPI signale les erreurs de syntaxe au fil de la frappe et propose l'autocomplétion. Swagger Editor le fait dans le navigateur ; la plupart des éditeurs de code ont aussi des extensions dédiées. Un validateur vérifie ensuite que le fichier respecte bien la spécification avant toute publication.

Imposer des règles de style avec un linter

Un linter va plus loin que la validation. Il vérifie vos propres règles : chaque endpoint a-t-il une description ? Les noms de champs suivent-ils tous la même convention ? Chaque réponse d'erreur utilise-t-elle le format commun ? Ces règles rendent la documentation homogène même quand plusieurs développeurs y contribuent.

Générer du code et des données simulées

À partir du contrat, des générateurs produisent des bibliothèques clientes dans différents langages, ou des squelettes de serveur. D'autres outils lancent un faux serveur qui renvoie les exemples du fichier : l'équipe front ou un partenaire peut commencer à travailler avant même que l'API réelle soit prête.

Tester que l'API respecte son contrat

Le risque principal d'une documentation, c'est qu'elle dérive du code. Les tests de contrat comparent les vraies réponses du serveur aux schémas déclarés. Si un développeur ajoute un champ sans mettre à jour le fichier, le test échoue. On les combine avec les tests unitaires et end-to-end déjà en place.

Tout brancher dans le pipeline

Le plus efficace est d'automatiser ces vérifications dans votre chaîne CI/CD. À chaque modification, le pipeline valide le fichier, applique le linter, compare avec la version précédente pour détecter les changements cassants, lance les tests de contrat, puis publie la documentation à jour. Personne n'a besoin d'y penser : c'est le système qui bloque l'erreur.

Combien de temps et quel budget : ce qui fait varier le résultat

Il n'existe pas de prix standard pour documenter une API. Le temps nécessaire dépend de plusieurs facteurs que vous pouvez évaluer vous-même avant de demander un devis. Les connaître vous aide aussi à comparer des propositions de manière juste.

Les facteurs qui pèsent le plus

Le coût caché de l'absence de documentation

Le vrai calcul compare le coût de la documentation à celui de son absence. Chaque nouvelle intégration qui nécessite des réunions, chaque bug causé par un champ mal compris, chaque développeur qui part avec la connaissance de l'API : ce sont des coûts réels, même s'ils ne figurent sur aucune facture. Une documentation tenue à jour se rentabilise souvent dès la deuxième ou troisième intégration.

Chez RankerSquare, nous intégrons la documentation OpenAPI dès la conception lorsque nous réalisons une création de logiciel ou une API sur mesure. Ce travail est chiffré sur devis, selon les critères ci-dessus. Pour les besoins plus simples, un site vitrine sur-mesure est proposé dès 19,90 € par mois en abonnement.

Les pièges fréquents et les points juridiques à vérifier

La plupart des documentations ratées le sont pour les mêmes raisons. Les connaître à l'avance permet de les éviter dès la première version du fichier.

Les erreurs techniques les plus courantes

Penser aussi à ceux qui lisent sans coder

Une bonne documentation ne parle pas qu'aux développeurs. Ajoutez une page d'introduction en langage clair : à quoi sert l'API, comment obtenir un accès, quel est le parcours typique. Un chef de projet ou un dirigeant doit pouvoir comprendre en quelques minutes ce que le service permet. Si votre API envoie aussi des notifications, expliquez la différence avec un webhook et documentez les deux.

Les aspects légaux à ne pas négliger

Dès qu'une API est ouverte à des tiers, la documentation a aussi une dimension juridique. Le bloc info permet de déclarer une licence et un lien vers des conditions d'utilisation : utilisez-les. Ces conditions précisent qui peut utiliser l'API, dans quelles limites, et ce qui se passe en cas d'abus ou d'arrêt du service.

Le RGPD s'applique aussi. Si l'API manipule des données personnelles, la documentation doit permettre de comprendre lesquelles circulent, sans en exposer aucune. Les exemples doivent rester fictifs, et la documentation privée ne doit pas devenir un point d'entrée vers des informations sensibles. Enfin, vérifiez les licences des outils et des bibliothèques générées que vous redistribuez à vos partenaires.

Questions fréquentes