Comment documenter une réponse compromise d'une liste de ressources en utilisant OpenAPI

Question

J'essaie de créer un fichier de documentation OpenAPI yml (via swagger). L'un de mes appels d'API renvoie une liste de ressources. Chaque ressource a des propriétés, un lien automatique et un lien vers un lien supplémentaire qui récupérera des «trucs» supplémentaires liés à la ressource.

S'il vous plaît voir l'exemple suivant:

[ 
    { 
    "name": "object-01", 
    "links": [ 
     { 
     "rel": "self", 
     "href": "http://localhost:8800/foo/object-01" 
     }, 
     { 
     "rel": "Supported stuff", 
     "href": "http://localhost:8800/foo/object-01/stuff" 
     } 
    ] 
    }, { 
    "name": "object-02", 
    "links": [ 
     { 
     "rel": "self", 
     "href": "http://localhost:8800/foo/object-02" 
     }, 
     { 
     "rel": "Supported stuff", 
     "href": "http://localhost:8800/foo/object-02/stuff" 
     } 
    ] 
    }, { 
    "name": "object-03", 
    "links": [ 
     { 
     "rel": "self", 
     "href": "http://localhost:8800/foo/object-03" 
     }, 
     { 
     "rel": "Supported stuff", 
     "href": "http://localhost:8800/foo/object-03/stuff" 
     } 
    ] 
    } 
] 

Je ne sais pas quelle est la bonne façon de documenter cela, c'est ce que j'ai en place en ce moment.

paths: 
    /foo/objects: 
     get: 
     operationId: getObject 
     responses: 
      '200': 
      description: Respresentation of objects 
      content: 
       application/json: 
       schema: 
        type: array 
        items: 
        $ref: '#/components/schemas/object' 
      links: 
       self: 
       $ref: '#/components/links/object' 
components: 
    links: 
    object: 
     operationId: getSObject 
    stuff: 
     operationId: getStuff 
    schemas: 
    object: 
     type: object 
     properties: 
     name: 
      type: string 

Mais je ne crois pas que cela représente adéquatement mon API.

Merci pour votre aide

Answer 1

Liens qui sont inclus dans la réponse réelle doivent être décrits dans le cadre du schéma du corps de réponse:

paths: 
    /foo/objects: 
    get: 
     operationId: getObject 
     responses: 
     '200': 
      description: Respresentation of objects 
      content: 
      application/json: 
       schema: 
       type: array 
       items: 
        $ref: '#/components/schemas/object' 
components: 
    schemas: 
    object: 
     type: object 
     properties: 
     name: 
      type: string 
     links:   # <------------- 
      type: array 
      items: 
      $ref: '#/components/schemas/link' 
    link: 
     type: object 
     properties: 
     rel: 
      type: string 
     href: 
      type: string 
      format: uri 

OpenAPI 3.0 links concept est similaire à HATEOAS, mais pas vraiment. Ces links sont utilisées pour décrire comment les valeurs renvoyées à partir d'une opération peuvent être utilisées comme entrée dans d'autres opérations. Par exemple, l'opération de création d'utilisateur renvoie l'ID utilisateur et cet ID peut être utilisé pour mettre à jour ou supprimer l'utilisateur. Cette page a quelques informations sur le links mot-clé: https://swagger.io/docs/specification/links