Comment améliorer la documentation des API avec Swagger et OpenAPI

Pourquoi la standardisation est essentielle pour l’utilisation d’API

La caractérisation est clé pour gérer des API spécifiques et partager les éléments de code nécessaires. Par le passé, le manque de standards et de paramètres clairs pour la documentation et le partage de données a limité l’émergence de ces interfaces de programmation. Avec une liste précise de toutes les méthodes, paramètres et réponses, les développeurs peuvent mieux comprendre les interactions clés entre les services Web et les composants logiciels.

Introduit en 2015 par Smartbear Software, la spécification Swagger a fait émerger un standard de langage de programmation agnostique pour développer des API RESTful. Swagger en a confié la gestion au projet OpenAPI contenu dans la Fondation Linux qui l’a renommé OpenAPI Specification (OAS). Celle-ci explicite les fonctionnalités d’une API. Elle définit le contrat et pourquoi l’interface de programmation interagit avec différentes ressources.

Les développeurs s’appuient sur l’OAS pour la normalisation du code. L'écosystème Swagger, lui, sert à accéder aux interfaces front-end, aux bibliothèques de code de bas niveau et aux outils de gestion des API.

Les avantages de la boîte à outils de Swagger

Une documentation concise et claire fait partie intégrante de la création d’API, d’autant plus que ces interfaces changent et évoluent rapidement pour supporter de nouveaux services et fonctionnalités. En définissant explicitement l’interaction des ressources d’une API, l’OAS répond à ce besoin de clarté. Ainsi, les machines et les humains, qu’ils soient développeurs ou non, peuvent facilement lire et comprendre l’OAS.

De par sa conception, le framework Swagger fonctionne avec le modèle REST pour les API publiques. Les API RESTful offrent un faible encombrement et utilisent la norme HTTP et le format populaire JSON, ce qui les rend flexibles et faciles à manipuler pour des mises à jour fréquentes. Ces attributs sont essentiels pour rationaliser la documentation des API RESTful et pour clarifier leur fonctionnement.

Si les équipes peuvent utiliser l’interface utilisateur open source de Swagger gratuitement, elle est également disponible dans la plateforme SwaggerHub, qui offre un certain nombre d’autres outils et fonctionnalités. SwaggerHub dépend de trois forfaits. Le premier est gratuit, le deuxième coûte 30 dollars par mois pour deux utilisateurs et le troisième, nommé Enterprise, est disponible en SaaS ou sur site, à partir de 25 utilisateurs. Vous trouverez ici des précisions sur les différents outils de l’écosystème Swagger :

SwaggerHub : il s’agit d’une plateforme de développement intégrée d’API. Elle permet aux équipes DevOps de collaborer et de coordonner leurs actions lors de la conception d’une API. Ils peuvent y intégrer leurs sets d’outils préférés. La plateforme doit également simplifier la rédaction de la documentation et les tests des services. Il est possible de l’utiliser pour gérer plusieurs versions d’une interface et ainsi itérer sans trop de problèmes. Par ailleurs, SwaggerHub doit fournir un accès et un hébergement sécurisés des définitions OAS à mesure que les stratégies API se développent et évoluent.

Swagger Editor : avec cet éditeur, les développeurs peuvent créer de la nouvelle documentation, concevoir des API ou en modifier des existantes. Le Swagger Editor doit évaluer instantanément le code par rapport à l’OAS puis identifie les erreurs de syntaxe. Les programmeurs peuvent tester et valider les API dans leurs navigateurs et enregistrer automatiquement ces mises à jour dans le cloud pour un accès facilité. Pour rédiger les descriptions, l’éditeur supporte les fichiers JSON et YAML. L’éditeur peut être utilisé depuis une interface Web ou déployé sur site après avoir installé le runtime NodeJS.

Swagger UI : cette interface utilisateur personnalisable peut être hébergée dans n’importe quel environnement serveur. Elle sert à visualiser les API et aide à convertir un contrat OAS, puis à l’intégrer dans une console afin d’interagir avec et de comprendre le comportement d’une API spécifique. Swagger UI offre une collection d’éléments HTML, JavaScript et CSS qui génèrent dynamiquement de la documentation d’une API basée sur la spécification OAS. Avec un simple workflow, les développeurs peuvent tester leurs API et envoyer rapidement des requêtes sur un navigateur pour déterminer comment elles vont réagir avant même d’avoir écrit une ligne de code.

Swagger Codegen : ce générateur de code rationalise le processus de création d’API en générant des appels vers le ou les serveurs (Stubs) et des kits de développement logiciel (SDK). En combinant Codegen et Swagger UI, il est possible de créer des bibliothèques clients, puis de générer du code basique afin de créer les éléments d’interactions entre une application et une API. Par ailleurs, les programmeurs peuvent rapidement convertir les définitions OAS en code grâce aux chaînes d’outillage personnalisées construites autour de Codegen.

Swagger Inspector : il s’agit d’un outil de test qui exécute également des requêtes API, valide les réponses et engendre les spécifications OpenAPI associées. Les équipes DevOps appellent chaque point de terminaison et utilisent la réponse afin de produire la documentation conforme à l’OAS. Il est possible d’enchaîner une série d’appels en direction de plusieurs endpoints afin d’accélérer cette étape.

Swagger, OAS 3.0 et au-delà

La mise à disposition d’OAS 3.0 a eu lieu en 2017. C’était la première « release » développée après la donation à la Fondation Linux. Cette version a consolidé sa position de leader des formats de spécification API. Elle a bénéficié d’une forte adoption qui a entraîné la création de nombreux outils.

OAS 3.0 propose une approche plus modulaire pour définir la surface d’interaction d’une API. Cela offre une plus grande polyvalence dans la description du modèle de requête et de réponse d’une interface de programmation. Cette dernière version doit faciliter la réutilisation des schémas, des composants, des spécifications, ainsi que la gestion des documents multipartites.

Elle doit également simplifier la manière de définir des actions pour les API. Néanmoins, les développeurs peuvent continuer à utiliser Swagger 2.0 avec SwaggerHub et les nouveaux outils ou avec d’autres plateformes de support.