аюсь создать файл документации OpenAPI yml (через swagger). Один из моих вызовов API возвращает список ресурсов. Каждый ресурс имеет свойства, собственную ссылку и ссылку на дополнительную ссылку, которая будет извлекать дополнительные «вещи», которые относятся к ресурсу.

Пожалуйста, смотрите следующий пример:

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

Я не уверен, как правильно документировать это, это то, что я сейчас имею в виду.

  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

Но я не верю, что это адекватно отражает мой API.

Спасибо за вашу помощь