Nous avons crée une jolie application web afin de visualiser des apis documentées avec Swagger 2. Basée sur l’interface bien connue Swagger UI, on y a ajouté du responsive, un design « Material » grâce à la libraire MaterializeCSS et de l’Angular 2.

Démo

Vous pouvez tester notre interface, par défaut c’est l’api d’exemple Swagger qui est utilisée mais vous pouvez évidemment la changer dans l’onglet « settings ».

Bien entendu, le projet github est à disposition.

Homepage

On retrouve sur la page d’accueil les informations globales de l’api.

Liste des apis

Présentation

On retrouve à gauche les apis classées par url avec la possibilité de faire une recherche sur le nom ou la description. Lorsque l’on clique sur une api (/pet par exemple), est affiché au centre la liste des ressources pour cette api.

Statistiques

Le bouton « stats » affiche une modal dans laquelle l’ensemble des temps d’éxecution sont représentés à travers un graphique (utilisant la librairie ChartJS) ce qui permet de voir l’evolution des temps de réponses de l’api.

Ce bouton n’apparait que si l’api à été consommée au moins une fois.

Il est possible de sélectionner d’autres apis dans la liste déroulante afin de comparer leurs temps de réponses:

Il est possible dans la page « settings » de modifier le type de graphique et de choisir entre « Line chart » et « Bar Chart ».

Détail d’une api

Le bouton « Try api » permet de tester directement cette dernière :

Présentation

On retrouve les informations les plus importantes telles que les informations générales, les formats de réponse et d’envoi acceptées, les paramètres et les différentes réponses retournées.

Paramètres

Lorsque un paramètre est renseigné, l’url présente dans « General Information » est dynamiquement construite si le paramètre est de type « query » ou « path », et elle est cliquable ce qui permet de tester directement l’url dans le navigateur. 

Plusieurs type de header « Accept » sont supportés:

• application/xml
• application/json
• multipart/form-data (upload supporté)
• application/x-www-form-urlencoded

Plusieurs types de paramètres sont supportés:

• Type path
• Type query
• Type form data

La majorité des paramètres sont renseignés grâce à un simple input de type text sauf :

• Pour les paramètres de type enum qui peuvent être renseignés via une liste déroulante (la sélection mutlitple est supportée) :

• Pour les paramètres de type « file » :

Dans le cas de paramètre de type « body », par exemple pour des api de type POST, PUT ou PATCH il est possible de génerer automatiquement un body d’exemple basé sur le model attendu. La génération prend en compte le format d’envoi sélectionné. Ainsi, si le format est « application/xml », lors du click sur le bouton « generate » un body d’exemple au format XML sera généré et idem pour le format « application/json ».

En cliquant sur le lien présent dans la colonne « Data type », une modal affiche les différents champs de l’entité attendu (Voir paragraphe « Liste des réponses »).

Format de réponse et d’envoi

Il est possible de sélectionner le format de réponse et/ou d’envoi gràce aux liste déroulantes (par exemple entre application/json et application/xml). Elles renseignent respectivement les headers http Content-Type et Accept.

Liste des réponses

En cliquant sur le lien présent dans la table « Response messages » et la colonne « Respone model » une modal s’affiche détaillant les différents champs de l’entité retournée. Il est possible de cliquer sur un sous type pour voir son contenu.

N’hésitez pas à tester l’interface avec votre propre api swagger 2 et à nous faire des retours.