[API] Ajouter une description sur les endpoints des services de l'API

[API] Ajouter une description sur les endpoints des services de l'API
0
Tags: #<Tag:0x00007f7697d2c958>

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.

Comment puis-je rajouter de champ ?

Merci d’avance

[Platform]
Status=OK
Version=4.0.P24
BuiltOn=2020-03-02 14:37 (revision 299f4a1ba30a4e87b2d2b5144482275299261126)
Encoding=UTF-8
EndpointIP=172.17.0.9
EndpointURL=http://39d90f1581bd:8080
TimeZone=Europe/Paris
SystemDate=2020-03-19 10:28:56

Je passe votre post en “feature request” car cela n’a pas été demandé jusqu’ici donc pas prévu dans le composant de mapping d’API.

Bonjour David,

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:

  1. 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
  2. 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)
  3. (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 beaucoup

Les objets JSON (et YAML) sont des format “unordered” donc on ne peut pas imposer un ordre sur les objets ou attributs, méthodes, …

Je regarderai ton point sur pour le /ping

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à)…

Je n’ai aucune idée de ce qui est possible ou pas en termes d’extension de la norme Swagger ou OpenAPI, je regarderai.

On a poussé l’évolution qui permet d’ajouter une description sur les opérations, cf. https://docs.simplicite.io/4.0/javadoc/com/simplicite/webapp/services/RESTMappedObjectsExternalObject.html#addOperationDesc(java.lang.String,java.lang.String,java.lang.String)

Ex:

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");*/

Au passage, le “Preview” des schemas OpenAPI et Swagger sur la page API Tester utilise désormais la lib SwaggerUI: