Question

我正在尝试创建OpenAPI yml文档文件（通过swagger）。我的一个API调用返回一个资源列表。每个资源都有属性，自我链接和指向附加链接的链接，这些链接将检索其他内容＆＃34;与资源有关。

请参阅以下示例：

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

如何使用OpenAPI记录受资源列表影响的响应

1 个答案: