Les services REST produits avec Adélia Studio peuvent être visualiser/tester via SwaggerUI (qui est embarqué par défaut dans la webapp Adélia). SwaggerUi : https://swagger.io/swagger-ui/
Par défaut, les apis sont regroupées par programme/classe ; l'ordre d'affichage est celui défini par le "scan" des classes.
Toutes les apis d'un service sont regroupées par défaut dans le même 'GroupName', celui défini implicitement ou explicitement via l'ordre : SW_CONFIGURER *SERVICE _WS_REST_SWAG_DESCRIPTION 'GroupName'.
Toutes les apis des services référençant le même GroupName sont regroupées.
A partir d'Adélia Studio 13 PTF08, l'ordre SW_CONFIGURER s'enrichit de l'attribut _WS_REST_SWAG_TAGS.
Désormais les apis/opérations d'un même service peuvent être regroupées dans des groupes distincts.
L'ordre SW_CONFIGURER *SERVICE _WS_REST_SWAG_DESCRIPTION 'DescGroupName1,DescGroupName2' permet alors d'associer une description à chacun des noms de groupe.
Exemples :
Permet de définir les groupes/tags du service.
Permet d'affecter une api/opération à un (ou plusieurs) groupe(s)/tag(s).
L'ordre d'affichage des classes/groupes peut être modifié a posteriori en modifiant le fichier swagger.html : définition de la propriété apisSorter de l'objet SwaggerUI
window.swaggerUi = new SwaggerUi({ ... apisSorter: "alpha", operationsSorter: function (a, b) { var order = { 'get': '0', 'post': '1', 'put': '2', 'delete': '3' }; return order[a.method].localeCompare(order[b.method]); }, ... }) |
La propriété apisSorter permet de trier les apis par groupe/classe, la propriété operationsSorter permet de trier les opérations (HTTP) :
- la valeur "alpha" permet d'obtenir un tri alphabétique.
- la fonction function(a,b) permet d'obtenir un tri en regard des valeurs retournées par la fonction de comparaison.
ou depuis Adelia Studio 13.9 (Cf. https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md), en modifiant le fichier index.html de l'archive swagger-ui-3.x.y
const ui = SwaggerUIBundle({ url: ..., dom_id: '#swagger-ui', operationsSorter:{ var order = { 'get': '0', 'post': '1', 'put': '2', 'delete': '3' }; return order[a.method].localeCompare(order[b.method]); }, tagsSorter:'alpha', ... }) |