Swagger : développer des API plus confortablement

La documentation est une étape très chronophage du développement et, bien souvent, les personnes extérieures au projet ignorent à quel point celle-ci peut s’avérer utile pour la maintenance et le développement ultérieur d’un système. On s’en aperçoit plus tard, lorsque ces tâches sont confiées à d’autres personnes que l’équipe à l’origine du système ; ce qui est davantage la règle que l’exception.

La documentation est particulièrement importante dans le cas d’une API, c’est-à-dire une Application Programming Interface, ou, en français, l’interface. Les interfaces connectent les logiciels entre eux, ainsi que les applications avec des sources de données et d’autres systèmes. Aujourd’hui, bien rares sont les cas où se connecter à un logiciel se passe de l’intervention d’un grand nombre d’API. Cependant, pour pouvoir comprendre une interface, il faut en comprendre la structure et les fonctions. C’est ce que permet la spécification OpenAPI Swagger, un format de description libre qui aide à consigner les différentes capacités d’une API. Avec Swagger, même les personnes qui n’ont pas directement pris part au processus de développement peuvent préparer une API : elles peuvent voir les interfaces utilisées et les documenter en même temps.

Par le passé, en raison des multiples technologies et langages de programmation existants, la description des API était très complexe. Une première grande étape dans le processus d’organisation des API a été la création du paradigme de programmation REST. Les sites Internet comme Google, Amazon et Twitter utilisent des API RESTful. Auparavant, les interfaces étaient décrites dans le Web Service Description Language WSDL. WSDL 2.0 permettait aussi de décrire des API REST d’un point de vue purement technique, une pratique cependant très peu commode pour les développeurs. Le Web Application Description Language (WADL) devait remédier à ce problème, mais n’a jamais été standardisé en raison de sa structure en XML.

Ainsi, Swagger est vite devenu la technologie la plus appréciée pour la documentation API. Plus précisément, pour documenter les API REST, très souvent utilisées. Swagger a été développé par Reverb, mais il s’agit désormais d’une solution indépendante et open source, sous la gouvernance de la fondation Linux, et plus précisément de l’OpenAPI Initiative. Avec ce changement d’acteurs, Swagger a été rebaptisé « spécification OpenAPI », même s’il reste officieusement connu sous le nom plus accrocheur de « Swagger ».

Swagger peut servir notamment dans des applications développées avec Spring Boot, comme expliqué brièvement dans la vidéo suivante (en anglais).

L’élément central de Swagger est, en fonction de son champ d’application, un fichier au format JSONP ou YAML. L’interface utilisateur, qui permet de représenter très facilement la documentation, fonctionne avec HTML et JavaScript. En principe, Swagger présente un format indépendant de tout langage informatique et lisible par une machine. À partir de l’interface utilisateur, on peut non seulement administrer la documentation, mais aussi s’en servir pour que Swagger effectue, par exemple, des tests ad hoc.

Swagger présente un avantage évident avec son mode développement, assuré par une bibliothèque centrale, Swagger Core. L’interface utilisateur s’appelle Swagger UI, le générateur de code Swagger Codegen, et il existe aussi un Swagger Editor.

Mais la grande force de Swagger, tout comme de nombreuses autres solutions open source, réside dans l’écosystème complet de GitHub. Là, les développeurs trouveront des générateurs de code pour presque tous les langages de programmation. Swagger documente chaque interface avec toutes les informations.

Le fichier de documentation commence par renseigner la version de la spécification utilisée, suivie de quelques informations générales sur l’API, clairement classées dans la catégorie info. Swagger distingue également l’hôte, le chemin et le schéma d’URL et les mentionne séparément. Ensuite seulement, on retrouve le type de média pour l’ensemble de l’API. Cette préparation s’apparente à un système complexe de fiches bristol.

Une fois cette catégorisation achevée, on représente les contenus : chemins, opérateurs et paramètres sont préparés avec leurs descriptions correspondantes. Les types de données sont administrés à part, dans une section dédiée. Swagger UI permet de représenter l’ensemble non seulement au format texte, mais aussi par une visualisation graphique. Une propriété surtout avantageuse lorsque les requêtes tests directes doivent être envoyées depuis le navigateur. Ce mélange entre documentation parfaite doublée de la possibilité de résoudre, en parallèle, des requêtes API directes, donne toute sa valeur à Swagger.

Développer une API exige de disposer d’une documentation ordonnée et compréhensible. Elle seule permet aux développeurs de se servir d’une interface. C’est encore plus vrai pour les API publiques : sans documentation, elles sont inutilisables pour la communauté, ne sont pas complétées et ne rencontrent aucun succès.

À l’heure actuelle, Swagger est la meilleure solution pour documenter une API REST, car le système est capable de représenter presque tous les services Web et informations ayant trait à l’interface. La documentation évolue en même temps que le système et enregistre automatiquement les modifications. Swagger se montre particulièrement efficace pour parvenir à ce résultat parce qu’il consigne la documentation d’une API REST directement dans son code.

Le point de départ de tout projet de développement d’API est soit le code de programmation (approche « Code first »), soit la description de l’interface (approche « Design first »). Dans le cas d’un projet en Code first, le point de départ convenu est le code. Swagger peut directement déduire la documentation à partir du code de programmation et produire des ressources indépendantes du langage de programmation utilisé, lisibles aussi bien par des machines que par des humains.

À l’autre bout du paradigme, l’approche Design first. Comme nous l’avons déjà évoqué, bien souvent, le client et le serveur sont gérés par des développeurs différents. L’approche Design first préconise de commencer par rédiger la description. Ensuite, les codes sont simplement générés par Swagger. Pour ce faire, il existe des générateurs pour tous les langages de programmation courants. Même les modèles peuvent encore être adaptés ou complétés.

Swagger propose ainsi presque automatiquement un code API cohérent. Si quelque chose ne correspond pas dans la programmation manuelle, on rencontre des erreurs de compilation, que l’utilisation d’un système d’intégration continue permet de visualiser automatiquement.

Les avantages de Swagger sont si convaincants qu’on peut tout à fait qualifier Swagger d’application standard exceptionnelle pour la description d’interfaces REST. Comme beaucoup d’autres applications open source, Swagger bénéficie d’une large diffusion, accompagnée d’un support complet. Le comité de Swagger se compose de géants de la tech, comme Microsoft, IBM ou Google, ce qui assure un soutien pérenne à la spécification OpenAPI, même s’il existe des alternatives. Le Restful API Modelling Language (RAML) s’appuie par exemple aussi sur le YAML et peut même créer des définitions encore plus complexes que celles de Swagger. Le créateur de RAML (Mulesoft) a cependant lui-même intégré l’OpenAPI Initiative.

L’intelligibilité et la lisibilité de la documentation de Swagger restent un petit inconvénient. La solution propose certes un format déjà plutôt bien structuré, mais il faut malgré tout un peu de temps pour se l’approprier. Pourtant, certains langages démontrent qu’il est possible de faire plus simple, comme API Blueprint et sa syntaxe en Markdown.

Sur le site de Swagger UI, on trouve le fichier ZIP complet de Swagger. Après le téléchargement, vous devez choisir d’exécuter Swagger en local ou sur un serveur.

Attention : si vous voulez l’exécuter en local, vous aurez besoin de MAMP. Vous devrez placer le dossier décompressé Swagger UI Master soit dans le dossier MAMP, soit sur le serveur. Ensuite, il suffit d’ouvrir l’URL du serveur ou de l’hôte local dans votre navigateur : Swagger s’ouvre automatiquement et la première documentation API se lance.

La version Web de l’éditeur de Swagger est encore plus simple. Celle-ci fonctionne sans problème dans votre navigateur et vous fait profiter, en plus de l’éditeur de texte, de l’affichage graphique de la documentation.

Ce court extrait d’un exemple Swagger permet déjà de comprendre la structure. Toutes les informations sont clairement identifiées et compréhensibles, indépendamment du langage de programmation.

Enfin, la documentation s’exporte directement dans un fichier YAML, ou bien se convertit d’abord au format JSON. C’est le fichier de documentation que Swagger UI est capable de lire. Les contenus affichés renseignent tout d’abord les chemins, les interfaces et les points de terminaison. Viennent ensuite les descriptions, les paramètres, ainsi que la réponse et ses significations. L’interface utilisateur de Swagger permet d’exécuter des tests ad hoc sur les points de terminaison.

Le grand atout de l’open source, c’est que l’on peut tester les outils gratuitement. C’est le cas pour Swagger UI et l’ensemble de ses outils. Ainsi, il est possible de se faire soi-même une idée des possibilités qu’offre Swagger.