OpenAPIを使用してリソースリストの感染を文書化する方法

Question

OpenAPI ymlドキュメントファイルを作成しようとしています（swagger経由で）。私のAPI呼び出しの1つがリソースのリストを返します。各リソースにはプロパティ、自己リンク、リソースに関連する追加の「もの」を取得する追加リンクへのリンクがあります。

次の例を参照してください。

[ 
    { 
    "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は、ある操作から返された値を他の操作の入力としてどのように使用できるかを記述するために使用されます。たとえば、ユーザー作成操作でユーザーIDが返され、このIDを使用してユーザーを更新または削除できます。このページには、linksキーワードの詳細がいくつか掲載されています：https://swagger.io/docs/specification/links