如何使用OpenAPI记录由资源列表组成的响应

Question

我正在尝试创建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。

感谢您的帮助

Answer 1

实际响应中包含的链接需要作为响应主体模式的一部分进行描述：