rest - 如何使用 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

包含在实际响应中的链接需要作为响应正文架构的一部分进行描述:

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 概念与 HATEOAS 相似，但并非如此。这些 links 用于描述从一个操作返回的值如何用作其他操作的输入。例如，create user 操作返回用户 ID，该 ID 可用于更新或删除用户。这个页面有一些关于 links 关键字的更多信息: https://swagger.io/docs/specification/links