Les Logic Apps ont récemment fait peau neuve, comme nous vous l’avions annoncé dans un précédent article sur « Logic Apps Standard :...
14 septembre 2023
Read this post in English
Comment déployer la documentation Swagger de votre API dans Azure en quelques minutes ?
Le développement et le déploiement des APIs est devenu un enjeu majeur pour toutes les organisations IT. D’après RapidAPI, on estime que 40% des plus grandes entreprises (>10K employés) ont plus de 250 APIs internes, et plus de 60% des plus petites entreprises utilisent jusqu’à 10 APIs en interne.
Face à ce constat, il est primordial de se doter d’une documentation accessible et diffusable pour que les APIs puissent facilement être partagées et adoptées.
Dans cet article, nous allons montrer plusieurs solutions pour déployer Swagger sur votre infrastructure Azure.
Prérequis
Nous allons considérer le scénario suivant : votre compagnie dispose de plusieurs APIs sur Azure et les équipes en charge de ces APIs ont enregistré chaque fichier OpenAPI sur un espace de stockage Azure. Le conteneur specs a été créé dans le blob storage et contient tous les fichiers OpenAPI. Elle souhaite mettre en place un ressource group dédié avec une solution basée sur Swagger pour exposer ses API à ses clients.
Déployer un docker Swagger sur Azure Application Service
Pour déployer Swagger sur Azure, on peut mettre en place un App Service qui hébergera une image docker de Swagger.
Il faut créer un App Service Plan (Linux / B1 par exemple) et un App Service permettant d’héberger une image docker Swagger (https://hub.docker.com/r/swaggerapi/swagger-ui).
Il reste ensuite à configurer l’Application Settings de l’App Service pour y ajouter les URL des fichiers OpenAPI disponibles sur le storage account.
La variable URLS va contenir la valeur suivante (remplacer <storage_account_name> par le nom de votre storage account) :
Dès que l’Application Settings est modifié, vous pouvez vous rendre sur le domaine de votre App Service pour constater que votre Swagger affiche la documentation de vos APIs.
Mettre à jour Swagger
Pour ajouter la documentation d’une nouvelle API, il faudra ajouter le fichier OpenAPI correspondant dans le storage account. Ensuite, il restera à mettre à jour la variable URLS dans l’Application Settings de l’App Service pour que les changements soient pris en compte.
Si un fichier OpenAPI existant a été mis à jour sur le storage account, un simple redémarrage de l’App Service permettra d’afficher la dernière version de la documentation.
Avantages et inconvénients à déployer un docker Swagger sur Azure Application Service
|
Avantages |
Inconvénients |
| Facilité de déploiement : Le déploiement de l’image docker permet de se concentrer uniquement sur la configuration de Swagger | Coût : La ressource Azure a un coût non négligeable (cf Pricing). La mise en place du scalling peut également engendrer des coûts supplémentaires. |
| Evolutivité : On peut utiliser la scalabilité de l’App Service pour adapter les besoins en fonction de la charge. | Performance variable : Les performances de l’App Service peuvent être limitées par les autres services partageant le même App Service Plan. De plus, la configuration sélectionnée pour l’App Service Plan peut influer sur les performances de l’application. |
| Sécurité : Cette solution autorise la mise en place de tous les services de sécurité disponibles pour un App Service (certificats SSL/TLS). |
Déployer un Swagger en site web statique
Pour déployer Swagger sur Azure, on peut choisir un site statique comme solution d’hébergement.
Dans ce scénario, nous aurons besoin d’une usine logicielle telle qu’Azure DevOps. Nous utiliserons un dépôt GIT pour héberger le code source (Azure Repos). Nous utiliserons Azure Pipelines pour déployer le code sur l’instance de Static Web App.
1. Créer une instance de static Web app sur le ressource group.
2. Une fois l’instance déployée, il faudra récupérer le token de déploiement depuis Azure.
3. Depuis Azure DevOps, créer un projet, puis un dépôt Git.
4. Télécharger la dernière release de Swagger.
5. Extraire le fichier et versionner le dossier /dist sur le dépôt Git (src/dist/).
6. Modifier le fichier swagger-initialiser.js pour remplacer la variable url par la variable suivante urls: [{ url: “https://<storage_account_name>.blob.core.windows.net/specs/petstore.yaml”, name: “Petstore” }, { url: “https:// <storage_account_name>.blob.core.windows.net/specs/zoom.yaml”, name: “Zoom” }],
7. Versionner la modification sur Git. Le dossier est prêt à être déployé sur un site statique.
8. Depuis Azure DevOps, créer un pipeline qui va contenir le code suivant en remplaçant le token de déploiement :
Une fois enregistré et exécuté, le pipeline copie le contenu du dossier /dist sur la static web app.
Vous pouvez vous rendre sur le domaine de votre static web app pour constater que votre Swagger est bien déployé.
Mettre à jour Swagger
Pour ajouter la documentation d’une nouvelle API, il faudra ajouter le fichier OpenAPI correspondant dans le Storage Account. Il faudra ensuite ajouter cette nouvelle entrée dans le fichier swagger-initialiser.js sur Git puis versionner ces modifications. Le pipeline détectera automatiquement les changements et mettra à jour le Swagger.
Si un fichier OpenAPI existant a été mis à jour sur le storage account, il suffira simplement de réexécuter le pipeline de déploiement pour que les changements soient pris en compte.
Avantages et inconvénients à déployer un Swagger en site web statique
| Avantages | Inconvénients |
| Simplicité de déploiement : Aucune configuration du site web statique n’est nécessaire, contrairement à l’App Service. | Sécurité : Mettre en place des mécanismes d’authentification est plus difficile dans un contexte statique. |
| Coût : La ressource Azure a un coût très faible en comparaison de l’équivalent en App Service (cf Pricing). | DevOps : La mise en place d’un site web statique pour héberger Swagger nécessite une usine logicielle de type Azure Devops ou Github pour gérer les dépôts Git et les pipelines de déploiement. |
| Performance : Le site web statique bénéficie de la mise en cache de contenu statique ce qui améliore sensiblement le temps de chargement et la performance de Swagger. |
L’essentiel à retenir
Nous avons vu dans cet article comment mettre en place Swagger sur un App Service ou sur une Static Web App dans Azure. Le choix d’une solution plutôt que l’autre pourra se faire en considérant les aspects d’authentification, de prix et des performances.
Liens utiles :
Vous souhaitez en savoir plus ou être accompagné par un expert ? Contactez-nous !
