Swagger : dé­ve­lop­per des API plus con­for­ta­ble­ment

La do­cu­men­ta­tion est une étape très chro­no­phage du dé­ve­lop­pe­ment et, bien souvent, les personnes ex­té­rieures au projet ignorent à quel point celle-ci peut s’avérer utile pour la main­te­nance et le dé­ve­lop­pe­ment 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 do­cu­men­ta­tion est par­ti­cu­liè­re­ment im­por­tante dans le cas d’une API, c’est-à-dire une Ap­pli­ca­tion Pro­gram­ming Interface, ou, en français, l’interface. Les in­ter­faces con­nec­tent les logiciels entre eux, ainsi que les ap­pli­ca­tions 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’in­ter­ven­tion d’un grand nombre d’API. Cependant, pour pouvoir com­prendre une interface, il faut en com­prendre la structure et les fonctions. C’est ce que permet la spé­ci­fi­ca­tion OpenAPI Swagger, un format de des­crip­tion libre qui aide à consigner les dif­fé­rentes capacités d’une API. Avec Swagger, même les personnes qui n’ont pas di­rec­te­ment pris part au processus de dé­ve­lop­pe­ment peuvent préparer une API : elles peuvent voir les in­ter­faces utilisées et les do­cu­men­ter en même temps.

Par le passé, en raison des multiples tech­no­lo­gies et langages de pro­gram­ma­tion existants, la des­crip­tion des API était très complexe. Une première grande étape dans le processus d’or­ga­ni­sa­tion des API a été la création du paradigme de pro­gram­ma­tion REST. Les sites Internet comme Google, Amazon et Twitter utilisent des API RESTful. Au­pa­ra­vant, les in­ter­faces étaient décrites dans le Web Service Des­crip­tion Language WSDL. WSDL 2.0 per­met­tait aussi de décrire des API REST d’un point de vue purement technique, une pratique cependant très peu commode pour les dé­ve­lop­peurs. Le Web Ap­pli­ca­tion Des­crip­tion Language (WADL) devait remédier à ce problème, mais n’a jamais été stan­dar­disé en raison de sa structure en XML.

Ainsi, Swagger est vite devenu la tech­no­lo­gie la plus appréciée pour la do­cu­men­ta­tion API. Plus pré­ci­sé­ment, pour do­cu­men­ter les API REST, très souvent utilisées. Swagger a été développé par Reverb, mais il s’agit désormais d’une solution in­dé­pen­dante et open source, sous la gou­ver­nance de la fondation Linux, et plus pré­ci­sé­ment de l’OpenAPI Ini­tia­tive. Avec ce chan­ge­ment d’acteurs, Swagger a été rebaptisé « spé­ci­fi­ca­tion OpenAPI », même s’il reste of­fi­cieu­se­ment connu sous le nom plus ac­cro­cheur de « Swagger ».

Swagger peut servir notamment dans des ap­pli­ca­tions dé­ve­lop­pées avec Spring Boot, comme expliqué dans la vidéo suivante.

L’élément central de Swagger est, en fonction de son champ d’ap­pli­ca­tion, un fichier au format JSONP ou YAML. L’interface uti­li­sa­teur, qui permet de re­pré­sen­ter très fa­ci­le­ment la do­cu­men­ta­tion, fonc­tionne avec HTML et Ja­vaS­cript. En principe, Swagger présente un format in­dé­pen­dant de tout langage in­for­ma­tique et lisible par une machine. À partir de l’interface uti­li­sa­teur, on peut non seulement ad­mi­nis­trer la do­cu­men­ta­tion, 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é­ve­lop­pe­ment, assuré par une bi­blio­thèque centrale, Swagger Core. L’interface uti­li­sa­teur s’appelle Swagger UI, le gé­né­ra­teur de code Swagger Codegen, et il existe aussi un Swagger Editor.

Mais la grande force de Swagger, tout comme de nom­breuses autres solutions open source, réside dans l’éco­sys­tème complet de GitHub. Là, les dé­ve­lop­peurs trou­ve­ront des gé­né­ra­teurs de code pour presque tous les langages de pro­gram­ma­tion. Swagger documente chaque interface avec toutes les in­for­ma­tions.

Le fichier de do­cu­men­ta­tion commence par ren­seig­ner la version de la spé­ci­fi­ca­tion utilisée, suivie de quelques in­for­ma­tions générales sur l’API, clai­re­ment 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é­pa­ré­ment. Ensuite seulement, on retrouve le type de média pour l’ensemble de l’API. Cette pré­pa­ra­tion s’apparente à un système complexe de fiches bristol.

Une fois cette ca­té­go­ri­sa­tion achevée, on re­pré­sente les contenus : chemins, opé­ra­teurs et pa­ra­mètres sont préparés avec leurs des­crip­tions cor­res­pon­dantes. Les types de données sont ad­mi­nis­trés à part, dans une section dédiée. Swagger UI permet de re­pré­sen­ter l’ensemble non seulement au format texte, mais aussi par une vi­sua­li­sa­tion graphique. Une propriété surtout avan­ta­geuse lorsque les requêtes tests directes doivent être envoyées depuis le na­vi­ga­teur. Ce mélange entre do­cu­men­ta­tion parfaite doublée de la pos­si­bi­lité de résoudre, en parallèle, des requêtes API directes, donne toute sa valeur à Swagger.

Dé­ve­lop­per une API exige de disposer d’une do­cu­men­ta­tion ordonnée et com­pré­hen­sible. Elle seule permet aux dé­ve­lop­peurs de se servir d’une interface. C’est encore plus vrai pour les API publiques : sans do­cu­men­ta­tion, elles sont inu­ti­li­sables pour la com­mu­nauté, ne sont pas com­plé­tées et ne ren­contrent aucun succès.

À l’heure actuelle, Swagger est la meilleure solution pour do­cu­men­ter une API REST, car le système est capable de re­pré­sen­ter presque tous les services Web et in­for­ma­tions ayant trait à l’interface. La do­cu­men­ta­tion évolue en même temps que le système et en­re­gistre au­to­ma­ti­que­ment les mo­di­fi­ca­tions. Swagger se montre par­ti­cu­liè­re­ment efficace pour parvenir à ce résultat parce qu’il consigne la do­cu­men­ta­tion d’une API REST di­rec­te­ment dans son code.

Le point de départ de tout projet de dé­ve­lop­pe­ment d’API est soit le code de pro­gram­ma­tion (approche « Code first »), soit la des­crip­tion 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 di­rec­te­ment déduire la do­cu­men­ta­tion à partir du code de pro­gram­ma­tion et produire des res­sources in­dé­pen­dantes du langage de pro­gram­ma­tion 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é­ve­lop­peurs dif­fé­rents. L’approche Design first préconise de commencer par rédiger la des­crip­tion. Ensuite, les codes sont sim­ple­ment générés par Swagger. Pour ce faire, il existe des gé­né­ra­teurs pour tous les langages de pro­gram­ma­tion courants. Même les modèles peuvent encore être adaptés ou complétés.

Swagger propose ainsi presque au­to­ma­ti­que­ment un code API cohérent. Si quelque chose ne cor­res­pond pas dans la pro­gram­ma­tion manuelle, on rencontre des erreurs de com­pi­la­tion, que l’uti­li­sa­tion d’un système d’in­té­gra­tion continue permet de vi­sua­li­ser au­to­ma­ti­que­ment.

Les avantages de Swagger sont si con­vain­cants qu’on peut tout à fait qualifier Swagger d’ap­pli­ca­tion standard ex­cep­tion­nelle pour la des­crip­tion d’in­ter­faces REST. Comme beaucoup d’autres ap­pli­ca­tions open source, Swagger bénéficie d’une large diffusion, ac­com­pag­né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é­ci­fi­ca­tion OpenAPI, même s’il existe des al­ter­na­tives. Le Restful API Modelling Language (RAML) s’appuie par exemple aussi sur le YAML et peut même créer des dé­fi­ni­tions encore plus complexes que celles de Swagger. Le créateur de RAML (Mulesoft) a cependant lui-même intégré l’OpenAPI Ini­tia­tive.

L’in­tel­li­gi­bi­lité et la li­si­bi­lité de la do­cu­men­ta­tion de Swagger restent un petit in­con­vé­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’ap­pro­prier. 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é­char­ge­ment, 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é­com­pressé 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 na­vi­ga­teur : Swagger s’ouvre au­to­ma­ti­que­ment et la première do­cu­men­ta­tion API se lance.

La version Web de l’éditeur de Swagger est encore plus simple. Celle-ci fonc­tionne sans problème dans votre na­vi­ga­teur et vous fait profiter, en plus de l’éditeur de texte, de l’affichage graphique de la do­cu­men­ta­tion.

Ce court extrait d’un exemple Swagger permet déjà de com­prendre la structure. Toutes les in­for­ma­tions sont clai­re­ment iden­ti­fiées et com­pré­hen­sibles, in­dé­pen­dam­ment du langage de pro­gram­ma­tion.

Enfin, la do­cu­men­ta­tion s’exporte di­rec­te­ment dans un fichier YAML, ou bien se convertit d’abord au format JSON. C’est le fichier de do­cu­men­ta­tion que Swagger UI est capable de lire. Les contenus affichés ren­seig­nent tout d’abord les chemins, les in­ter­faces et les points de ter­mi­nai­son. Viennent ensuite les des­crip­tions, les pa­ra­mètres, ainsi que la réponse et ses sig­ni­fi­ca­tions. L’interface uti­li­sa­teur de Swagger permet d’exécuter des tests ad hoc sur les points de ter­mi­nai­son.

Le grand atout de l’open source, c’est que l’on peut tester les outils gra­tui­te­ment. 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 pos­si­bi­li­tés qu’offre Swagger.