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.

Qu’est-ce que Swagger ?

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.

Pour afficher cette vidéo, des cookies de tiers sont né­ces­saires. Vous pouvez consulter et modifier vos pa­ra­mètres de cookies ici.

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.

Dans quels cas utilise-t-on 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.

Swagger : les avantages d’une pro­gram­ma­tion bien ordonnée

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.

Swagger : un exemple pratique pour démarrer

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.

Swagger: "2.0"
info:
    description: "Ceci est un exemple Swagger"
    version: "1.0.0"
    title: "Exemple Swagger"
    termsOfService: "http://Swagger.io/terms/"
basePath: "/v2"
tags:
- name: "Exemple"
    description: "Exemples pour Swagger"
    externalDocs:
        description: "En savoir plus"
        url: "http://example.org"
schemes:
- "https"
- "http"
paths:
    /Exemple:
    /Exemple/Contenu:
        get:
            tags:
            - "Exemple"
            summary: "Interroger un élément d’exemple"
            produces:
            - "application/json"
            parameters: []
            responses:
                "200":
                    description: "successful operation"
                    schema:
                        type: "object"
                        additionalProperties:
                            type: "integer"
                            format: "int32"
            security:
            - api_key: []

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.