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

Question

我正在尝试创建 OpenAPI yml 文档文件（通过 swagger）。我的一个 API 调用 returns 资源列表。每个资源都有属性，一个 self link 和一个 link 到一个额外的 link，它将检索与资源相关的额外 "stuff"。

请看下面的例子：

[
  {
    "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 用于描述如何将一个操作返回的值用作其他操作的输入。例如，创建用户操作returns用户ID，而这个ID可以用来更新或删除用户。此页面包含有关 links 关键字的更多信息：https://swagger.io/docs/specification/links

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

How to document a response comprised of a list of resources using OpenAPI

rest

hateoas

swagger-editor

openapi