Swagger UI avec Angular 2 et MaterializeCSS
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.