Estou tentando criar o arquivo de documentação OpenAPI yml (via swagger). Uma das minhas chamadas de API retorna uma lista de recursos. Cada recurso possui propriedades, um link próprio e um link para um link adicional que recuperará "itens" adicionais relacionados ao recurso.

Por favor, veja o seguinte exemplo:

[
  {
    "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"
      }
    ]
  }
]

Não sei ao certo qual é a maneira correta de documentar isso, é isso que tenho no momento.

  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

Mas não acredito que isso represente adequadamente minha API.

Obrigado pela ajuda