OpenAPI est une façon standard de décrire une API web dans un seul fichier. Ce fichier liste chaque adresse proposée par l'API, ce qu'elle accepte, ce qu'elle renvoie et ce qui peut mal tourner. Les humains le lisent comme une documentation, et les logiciels s'en servent pour générer automatiquement des pages de test, du code et des vérifications.

On l'appelle aussi Swagger, son nom d'origine. Si vous faites appel à un développeur pour relier deux outils, commandez une application sur mesure ou cherchez à savoir si une plateforme prend les intégrations au sérieux, savoir ce qu'est un fichier OpenAPI vous aide à exiger le bon livrable et à ne pas payer deux fois le même travail.

Qu'est-ce qu'OpenAPI ?

La spécification OpenAPI est un standard ouvert, maintenu par l'OpenAPI Initiative au sein de la Linux Foundation, pour décrire des API REST. Un document OpenAPI est un fichier texte écrit en YAML ou en JSON. Ce n'est pas du code qui s'exécute. C'est une description précise, un peu comme une fiche technique détaillée pour une API.

Un fichier OpenAPI contient en général :

  • Des informations générales : le nom de l'API, sa version, un contact et l'adresse de base.
  • Des chemins (paths) : chaque endpoint, comme /orders ou /products/{id}, et les méthodes autorisées sur chacun (GET, POST, PATCH, DELETE).
  • Des paramètres : filtres et options, comme « status=paid » ou « page=2 ».
  • Des corps de requête et de réponse : les champs exacts, leur type et ceux qui sont obligatoires. Par exemple, une commande a un identifiant, un total en centimes, un code devise et une liste de lignes.
  • Des réponses d'erreur : ce que renvoie l'API en cas d'échec, comme un 404 pour une commande inconnue.
  • La sécurité : la façon dont les clients prouvent leur identité, par clé d'API ou jeton OAuth.

Un mot sur les noms. Swagger est né en 2011, à la fois spécification et ensemble d'outils. En 2015, la spécification a été confiée à une fondation neutre et rebaptisée OpenAPI. Les outils ont gardé le nom Swagger. Aujourd'hui, OpenAPI désigne donc le format, et Swagger des outils qui l'exploitent, le plus connu étant Swagger UI, qui transforme un fichier OpenAPI en page de documentation interactive. Beaucoup de gens disent encore « fichier Swagger » pour parler d'un document OpenAPI.

OpenAPI n'est pas une API en soi, et ne rend pas une API bonne ou sûre. Il décrit des API de style REST. Les API GraphQL utilisent leur propre schéma, et les API orientées événements utilisent souvent un format cousin, AsyncAPI.

Pourquoi c'est important

Un fichier OpenAPI transforme des connaissances floues sur une API en un document partagé et vérifiable. Cela fait économiser de l'argent à trois endroits.

D'abord, les devis deviennent plus justes. Imaginons une marque à 800 commandes par mois qui veut relier sa boutique en ligne à son entrepôt. Le freelance chiffre 4 jours à 500 €, soit 2 000 €. Si les deux API publient un fichier OpenAPI, il peut vérifier avant de chiffrer que l'entrepôt accepte les commandes avec message cadeau et renvoie les numéros de suivi. Sans ce fichier, la découverte se fait le troisième jour, et le devis gonfle de 2 jours, soit 1 000 €, ou la fonctionnalité passe à la trappe.

Ensuite, le travail va plus vite. Des outils lisent le fichier OpenAPI et génèrent automatiquement du code client, des requêtes de test et des serveurs de maquette. Un développeur qui aurait passé une journée à écrire à la main le code des requêtes peut partir d'un code généré en une heure.

Enfin, vous gardez ce que vous avez payé. Si vous commandez une API sur mesure, le fichier OpenAPI est le mode d'emploi qui permet au développeur suivant de reprendre le projet. Une agence qui vous laisse du code sans description vous rend dépendant d'elle. Avec un fichier OpenAPI complet, un nouveau freelance comprend l'API en quelques heures, pas en quelques semaines.

Comment ça marche

OpenAPI s'inscrit dans la vie d'une API de la façon suivante :

  • Quelqu'un écrit ou génère le fichier. En conception API-first, l'équipe l'écrit à la main avant de coder. Dans un projet code-first, un framework le génère à partir du code.
  • Le fichier est relu. Fondateurs et développeurs vérifient que les endpoints et les champs correspondent aux besoins métier.
  • Des outils lisent le fichier. Swagger UI et ses équivalents affichent une documentation lisible et cliquable. D'autres génèrent des bibliothèques clientes dans de nombreux langages ou des serveurs de maquette qui renvoient des données d'exemple.
  • Les développeurs testent des appels. Depuis la page de documentation, ils envoient de vraies requêtes avec une clé de test et voient les réponses.
  • Des vérifications automatiques comparent la réalité au fichier. Des tests confirment que l'API en production renvoie exactement les champs et les codes promis.
  • Le fichier est versionné. Quand l'API change, le fichier change avec elle, et le numéro de version indique aux intégrateurs ce qui a bougé.

Les versions majeures actuelles sont la 3.0 et la 3.1. Les documents plus anciens en version 2.0 s'appellent encore Swagger 2.0.

Repères et exemples

Quelques repères utiles :

  • Taille : une petite API de 10 à 20 endpoints tient souvent dans un fichier OpenAPI de 500 à 2 000 lignes. Les grandes plateformes publient des fichiers de plusieurs dizaines de milliers de lignes.
  • Effort : rédiger un fichier OpenAPI propre pour une petite API existante demande environ 1 à 3 jours à un développeur. Le tenir à jour coûte quelques heures par version.
  • Génération de code : le code client généré peut faire gagner 1 à 3 jours sur une intégration classique, selon le langage et la qualité du fichier.
  • Adoption : la plupart des grands prestataires de paiement, d'expédition et de messagerie publient une description OpenAPI ou construisent leur documentation à partir d'elle.

Situations courantes :

  • Un freelance importe le fichier OpenAPI d'un prestataire de paiement et teste chaque appel avant d'écrire la moindre ligne d'intégration.
  • Une agence qui développe un back-office de réservation sur mesure livre le fichier OpenAPI avec le code, pour que le développeur mobile du client puisse démarrer.
  • Le développeur d'une marque génère un serveur de maquette à partir du fichier pour construire un portail revendeurs pendant que la vraie API se termine.
  • Une fondatrice exige le fichier OpenAPI dans le contrat pour qu'un futur développeur puisse reprendre le projet sans rétro-ingénierie.

Erreurs fréquentes

  • Considérer le fichier comme facultatif. Sans lui, la connaissance reste dans la tête d'un seul développeur. Inscrivez-le dans les livrables.
  • Le laisser diverger du code. Un fichier qui décrit l'API de l'an dernier induit en erreur tous ceux qui le lisent.
  • Oublier les erreurs et les exemples. Un fichier qui liste les champs sans cas d'erreur ni valeurs d'exemple oblige les développeurs à deviner.
  • Publier par mégarde des endpoints internes. Un endpoint d'administration décrit dans un fichier public attire une attention indésirable. Relisez ce que vous publiez.
  • Confondre documentation et sécurité. Documenter une API ne la protège pas. L'authentification et les droits d'accès restent à construire.

Bonnes pratiques

  • Inscrivez-le au contrat. Quand vous commandez une API, listez un fichier OpenAPI complet et à jour parmi les livrables qui vous appartiennent.
  • Demandez des exemples sur chaque endpoint. Des requêtes et réponses d'exemple rendent le fichier lisible, même pour des non-développeurs.
  • Générez-le ou vérifiez-le automatiquement. Soit le fichier est produit à partir du code, soit le code est testé par rapport au fichier à chaque version.
  • Utilisez des noms métier clairs. Des champs comme « shipping_cost » ou « gift_message » se lisent mieux que « field_12 ».
  • Tenez un journal des changements à côté. Une courte note par version indique aux intégrateurs ce qui a changé et ce qui risque de casser.
  • Publiez-le avec une documentation lisible. Associez le fichier à un outil comme Swagger UI pour que vos partenaires explorent l'API sans logiciel particulier.

Dans Roctify

Roctify est un SaaS et une plateforme no-code : vous gérez votre boutique sans lire de description d'API. Produits, variantes, stock, clients et commandes vivent dans un catalogue partagé utilisé par votre page lien en bio, votre boutique en ligne et votre checkout, et Roctify connecte Stripe et PayPal pour les paiements. Le travail d'intégration qu'un fichier OpenAPI facilite d'habitude est, pour la plupart des vendeurs, déjà fait dans la plateforme.

Roctify ne propose pas d'API publique ni de description OpenAPI aujourd'hui. Si vous avez besoin de vos données ailleurs, le plan Pro inclut rapports et exports, et les intégrations sur mesure pour les activités plus importantes se discutent dans le cadre du plan Enterprise. Quand vous évaluez d'autres outils à utiliser à côté de votre boutique, un fichier OpenAPI publié est un bon signe que leurs intégrations sont bien entretenues.

FAQ

OpenAPI et Swagger, c'est la même chose ?

Presque. Swagger était le nom d'origine de la spécification. Depuis 2015, la spécification s'appelle OpenAPI, et Swagger désigne une famille d'outils qui l'exploitent, comme Swagger UI. Les deux mots restent utilisés pour parler du fichier.

Dois-je lire moi-même un fichier OpenAPI ?

En général, non. C'est votre développeur qui le lit. Ce qui compte pour vous, c'est de demander si les outils que vous voulez connecter en publient un, et d'en exiger un quand vous commandez une API sur mesure.

OpenAPI peut-il décrire n'importe quelle API ?

Il est conçu pour les API HTTP de style REST. Les API GraphQL sont décrites par leur propre schéma, et les API orientées événements utilisent souvent AsyncAPI. La plupart des API web que vous croiserez en tant que vendeur sont de type REST, donc OpenAPI les couvre.