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

    swagger_home

     

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

    Liste des apis

    Présentation

    swagger_api_list

    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.

    swagger_modal_chart

     

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

    swagger_modal_chart_comparison

    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 :

    swagger_detail

    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) :

    swagger_select

     

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

     

    swagger_inputtt_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 ».

     

    swagger_body_json

    swagger_body_xml

    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.

    swagger_modal_type

     

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