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