Comment designer et documenter ses API

avec la suite SwaggerHub ? _

Introduction

Lors du premier article concernant les outils pour le design des API, nous avons présenté la suite Stoplight. Pour ce second article nous allons présenter la suite SwaggerHub du site swagger.io de la société Smartbear.


En effet la société Smartbear propose un outil open source de tests des web services depuis plusieurs années, SoapUI.

SoapUI est incontournable pour automatiser les tests des web services, il supporte les formats SOAP et REST et les protocoles HTTP/HTTPS et JMS.


Un des atouts de SoapUI est la validation des WSDL, les interfaces des web services.


Avec l’arrivée massive des API REST dans la stratégie de digitalisation des entreprises, la société Smartbear a développé dans un premier temps l’outil ReadyAPI qui est une version complète de SoapUI pour les tests des web services et des API.

SwaggerHub

La suite de SwaggerHub quant à elle s’oriente vers le design des API, c’est-à-dire la définition de l’interface des services qui vont être exposés aux partenaires ou aux applications internes du système d’information.


Swagger propose une offre open source et une offre Entreprise.

L’outil principal de la solution est Swagger UI qui permet de visualiser graphiquement le fichier JSON (ou YAML) qui définit l’interface d’un API, on parle de la norme OpenAPI (anciennement Swagger, d’où le nom de la suite).


Si la représentation graphique de l’interface est très bien réalisée, on voit bien dans l’exemple suivant que le code JSON est parfois difficile à lire.


L’éditeur permet d’avoir les deux vues (code JSON et graphique) sur la même page, tandis que l’outil affiche les erreurs présentes dans le code JSON.


La version Entreprise de SwaggerHub permet de créer une équipe et de travailler sur les mêmes fichiers OpenAPI ou Swagger :

Les fichiers Swaggers peuvent être synchronisés automatiquement avec GitHub.


SwaggerHub permet de travailler en équipe pour définir les interfaces des API, dans un pur esprit Design-First. On peut créer des clients avec les langages les plus connus et on peut générer des bouchons des services.


Associé avec ReadyAPI pour tester les API une solution complète est disponible pour les équipes qui développent et déploient des API REST. La documentation des API sera quant à elle plus facile à réaliser et l’expérience des utilisateurs sera améliorée.

Découvrir également

icone integration digitale
API et intégration

S'ouvrir et construire des écosystèmes numériques .

API et intégration

de l'API Management
de l'API Management
API et intégration
13 minutes
Revue des leaders
de l'API Management _