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

Question

我正在尝试创建OpenAPI yml文档文件（通过放大器）。我的一个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用于描述如何将一个操作返回的值用作其他操作的输入。例如，创建用户操作返回用户标识，并且此标识可用于更新或删除用户。此页面有一些关于links关键字的更多信息：https://swagger.io/docs/specification/links