Ajout manuel de ligne dans le générateur de swagger automatique

Bonjour,

Pour notre projet, on utilise le générateur automatique de swagger de Simplicité (addObject, addFields, etc) et il marche très bien
Cependant, voulant étoffer notre swagger, on voudrait rajouter des lignes supplémentaires dans le swagger.
Meme si la génération du swagger se fait rarement, on voudrait que les lignes supplémentaires soient tout le temps présentent
Je voulais donc savoir si il existait une méthode ou une possibilité pour que l’on puisse rajouter, via le code, ces lignes d’informations pour le swagger qui se génère automatiquement ?

[Platform]
Status=OK
Version=4.0.P24
BuiltOn=2020-05-19 22:06 (revision 25ed8fe0efec3d050cf138472f7fff72ece375da)
DBPatchLevel=P24;a67483e9ad7725b18d468ff8ff591fff

Cordialement,
KWu

Je n’ai pas compris ce qui vous manque dans les schémas Swagger/OpenAPI générés par défaut…

Il n’y a pas de manque dans le schéma, je voudrais faire un ajout d’information dans mon swagger (config, commentaire, information, etc)

Il y a déjà des méthodes pour ajouter des commentaires & des exemples, cf. https://docs.simplicite.io/4.0/javadoc/com/simplicite/webapp/services/RESTMappedObjectsExternalObject.html

Le reste est généré automatiquement dans le contexte dans lequel vous générez le schéma (ex: les infos de “configuration” techniques URLs/hosts/paths/… n’ont donc, logiquement, aucune de raison d’être modifiées, ni via une méthode, ni manuellement).

Mais peut être manque-t-il des choses, d’où ma question => que vous manque-t-il exactement ?

Dans un des exemples que j’ai, il m’est demandé de rajouter ces lignes dans les début du swagger généré automatiquement, sinon certaines parties ne sont pas totalement configurés

       - Purposes
       - Sub-purposes
       tags:
         required: true
         type: string
         description: Unique technical row ID
         name: rowId
       - in: path
       parameters:
           description: Internal server error
             $ref: '#/definitions/Error500'
           schema:
         '500':
           description: Unauthorized
             $ref: '#/definitions/Error401'
           schema:
         '401':
           description: Bad request
             $ref: '#/definitions/Error400'
           schema:
         '400':
           description: purposes identified by rowId sub-purposes sub-purposes
             $ref: '#/definitions/ArrayOfSub-purposes'
           schema:
         '200':
       responses:
       operationId: purposes-sub-purposes-get
       - application/json
       produces:
       - bearerAuth: []
       security:
       summary: Get records for sub-purposes that purposes identified by rowId sub-purposes
     get:
     # linked operation
   /purposes/{rowId}/sub-purposes:

C’est ce genre d’information que je voudrais rajouter dans mon swagger

Il n’y a aucune raison de toucher les paths et autres paramètres générés automatiquement.

Donc à nouveau je ne comprend toujours ce qui vous manque. Quand vous dites “ces lignes”, ou “ce genre d’information” de quelles lignes parlez vous exactement ?

Le terme “ligne” (ou “information”) ne veut rien dire de précis dans le contexte d’un schema OpenAPI/Swagger dont les “lignes” on une signification précise, un format précis, une indentation précise, une fonction précise, … et doivent suivre une norme précise (OpenAPI 3.* et/ou Swagger 2.*)

Bref dites moi precisément ce que vous devez ajouter manuellement et je pourrai alors vous dire:

  • si une API Java permet déjà de le faire
  • ou si c’est une évolution envisageable
  • ou si c’est un cas très particulier qui n’a pas sa place dans du code générique (et que vous devrez donc continuer à ajouter à la main).

Bonjour David, il s’agit de path décrivant le parcours de relations du modèle explicitement mappées par un addRefField(…):

/basepath/resource/{rowId}/relation

Le runtime Simplicité sait très bien opérer ces resources et traverser leurs relations (si elle sont mappées explicitement) mais le swagger openapi généré ne contient pas le path correspondant…

Bruno

OK compris.

Je vais regarder ce que signifierai de générer tous les paths possibles mais ça va forcément compliquer / faire grossir abusivement les schémas si on génère tous les chemins possibles en se basant sur les relations (car en “navigation” ça marche à N niveaux: /obj1/rowID1/obj2/rowID2/obj3/...)

OK, je vois.

A priori, je n’ai identifié que des cas d’usage que pour des navigations de rang 1 pour l’instant mais si le runtime sait gérer les appels plus en profondeur, c’est peut-être dommage de passer à côté.

J’ai testé les calls suivants:

De mon point de vue, la gestion de la navigation de rang 1 est suffisante et reste par ailleurs cohérente avec le contenu du bloc _links inclus dans la réponse du runtime:

{
  "_links":[{"rel":"delivers","href":"softwareProductPublishers/63/delivers"}],
  "softwareProductPublisherState":"ACT",
  "softwareProductPublisherSegment":"EMG",
  "softwareProductPublisherName":"OPENSOURCE",
  "softwareProductPublisherRelationshipAssessment":"NEU",
  "rowId":"63"
}

OK je regarde quels impacts aurait d’ajouter les paths des liens de niveau 1

Merci beaucoup!

Nous considérons bien sur uniquement les relations explicitement mappées par un addRefField(…):

addRefField("softwareProducts",
  "softwareProductPublishers",
  "softwareProductPublisherId",
  "SwPublisherId",
  "delivers",
  false);

Ce qui me fait réagir aussi sur le flag “embedded”… a priori, si on a activé l’embedding, la liste liée fait partie de la réponse et le path devient inutile…

Donc, toujours a priori, les cas d’usage identifiés seraient uniquement les addRefField non embedded.

Bonjour,

Avez-vous eu un retour par rapport à cette demande ?

Cordialement,
KWu

Non nous n’avons pas encore eu le temps d’adresser ce change request.
Nous vous tiendrons au courant