Bonjour
mon api référant m’a demandé de mettre une description au niveau des endpoints. Une description différente par méthode.
Actuellement, il y a un champ summary qui est autogénéré. Nous souhaiterions ajouter un champ description.
je profite de cette demande pour compléter avec quelques points concernant la génération de la doc openapi (yml ou json) qui pourraient peut-être être pris en compte dans la même itération:
Dans la liste des tags, les objets sont listés dans l’ordre documenté pour l’export (obo_exportorder) ou à défaut par ordre alphabétique du nom de l’objet
Dans les modèles et les paramètres d’opérations, les champs d’objet sont listés dans l’ordre documenté (obf_order) - les paramètres de query restant en haut (page/pagesize)
(si pas compliqué, ce que je crois comprendre), restituer la opération “ping” dans une namespace “Common” cité par ailleurs dans les tags (actuellement, l’opération ping est uniquement décrite par son path et n’est donc raccrochée à rien -> restitué en “default” par les swagger editors)
Merci David pour ton retour rapide.
c’est bien dommage (cf. unordered).
J’ai bien vu que dans la littérature relative au swagger, il était question de apisSorter / operationsSorter mais ces règles de présentation sont à implémenter dans la configuration de l’éditeur de swagger utilisé par le lecteur… J’aurai préféré prédéfinir l’ordre de rendu des tags dans le fichier yml (et l’export order me semble pertinent dans ce contexte) sachant bien que l’ordre d’affichage étant en dernière instance celui voulu par l’utilisateur qui aura défini apisSorter (il doit bien en avoir quelques-uns qui le font).
On utilise des libs JSON (org.json) et YAML (snakeyaml) qui ne tiennent - légitimement - aucun compte de l’ordre dans lequel on construit le JSON (car ça on le fait bien sûr dans un ordre déterministe à l’origine).
Ok, je comprends…
Est-il envisageable d’étendre la spécification du tags object avec un attribut additionnel (x-tag-order par exemple) reprenant la valeur obo_exportorder si définie?
Pour la demande concernant l’ordre des champs d’objets (paramètres, modèles) c’est une autre paire de manche apparemment (j’ai trouvé des infos sur sortParamsByRequiredFlag également à mettre en place du côté du swagger UI mais ça ne fait pas non plus ce que je voudrais et il semble que l’objet Parameter ne soit pas extensible pour pouvoir y intégrer aussi un x-param-order).
Ce sujet (maîtriser l’ordre dans lequel sont rendus les “choses” semble ouvert depuis quelque temps déjà)…
addOperationDesc("products", OPERATION_SEARCH, "This is the **search** operation for the _product_ business object");
addOperationDesc("products", OPERATION_GET, "This is the **get** operation for the _product_ business object");
addOperationDesc("products", OPERATION_CREATE, "This is the **create** operation for the _product_ business object");
addOperationDesc("products", OPERATION_UPDATE, "This is the **update** operation for the _product_ business object");
addOperationDesc("products", OPERATION_DELETE, "This is the **delete** operation for the _product_ business object");
addOperationDesc(null, OPERATION_PING, "This is the **ping** operation");*/