web-dev-qa-db-ja.com

OpenAPI 3で配列項目の例を参照する方法は？

このスキーマ定義を使用する：

schemas:
  AllContacts:
    type: array
    items:
      $ref: '#/definitions/ContactModel1'
    example:
      - id: 1
        firstName: Sherlock
        lastName: Holmes
      - id: 2
        firstName: John
        lastName: Watson

私はこの期待される結果を得ます：

[
  {
     "id": 1,
     "firstName": "Sherlock",
     "lastName": "Holmes"
  },
  {
     "id": 2,
     "firstName": "John",
     "lastName": "Watson"
  }
]

次に、単一のユーザー（ContactModel1）とユーザーの配列の一部（AllContacts）の両方でホームズの例を再利用したいと思います。しかし、参照されている例を使用する場合：

schemas:

  AllContacts:
    type: array
    items:
      $ref: '#/definitions/ContactModel1'
    example:
      Homes:
        $ref: '#/components/examples/Homes'
      Watson:
        $ref: '#/components/examples/Watson'

  examples:

    Holmes:
      value:
        id: 1
        first_name: Sherlock
        last_name: Holmes

    Watson:
      value:
        id: 2
        first_name: John
        last_name: Watson

Swagger UIで次の予期しない結果が表示されます。

[
  {
    "value": {
      "id": 1,
      "first_name": "Sherlock",
      "last_name": "Holmes",
    },
    "$$ref": "#/components/examples/Holmes"
  },
  {
    "value": {
      "id": 2,
      "first_name": "John",
      "last_name": "Watson",
    },
    "$$ref": "#/components/examples/Watson"
  }
]

GET /user/1の同様の予期しない例：

[
  {
    "value": {
      "id": 1,
      "first_name": "Sherlock",
      "last_name": "Holmes",
    },
    "$$ref": "#/components/examples/Holmes"
  }
]

何が悪いのですか？

私はこのドキュメントを参照として使用しています：
https://swagger.io/docs/specification/adding-examples/#reuse

swagger-uiopenapi
7
Old Man Walter

これは有効な定義ではありません：

components:
  schemas:
    AllContacts:
      type: array
      items:
        $ref: '#/definitions/ContactModel1'
      example:
        Homes:
          $ref: '#/components/examples/Homes'
        Watson:
          $ref: '#/components/examples/Watson'

1）example構文が間違っています。 OpenAPI 3.0には、例としてexample（単数）とexamples（複数）の2つのキーワードがあります。彼らは異なる働きをします：

  • exampleはインラインの例を必要とし、$refをサポートしません。
  • examplesは、名前付きの例のマップ（コレクション）です。これは$refをサポートしますが、$ref全体の例のみが可能で、例の個々の部分はできません。これは、複数の$refsから例を作成することができないことも意味します。すべての要素が複数形examplesをサポートしているわけではないことに注意してください。

Swagger UIユーザーへの注意：Swagger UIは現在example（単数）をサポートしていますが、examples（複数）はサポートしていません。 examplesのサポートは この問題 で追跡されます。

2） スキーマオブジェクト は、単数形exampleのみをサポートし、複数形examplesはサポートしません。つまり、スキーマはインラインの例のみをサポートします。

3）OpenAPI 3.0では、スキーマ参照は#/components/schemas/...ではなく#/definitions/...の形式を使用します

ユーザーの配列と単一のユーザーの両方で、ホームズに同じ例の定義を使用したいと思います。

この場合、例の一部を再利用する方法はありません。両方のスキーマで例の値を繰り返す必要があります。

components:
  schemas:
    ContactModel1:
      type: object
      properties:
        ...
      example:
        id: 1
        first_name: Sherlock
        last_name: Holmes

    AllContacts:
      type: array
      items:
        $ref: '#/components/schemas/ContactModel1'
      example:
        - id: 1
          first_name: Sherlock
          last_name: Holmes
        - id: 2
          first_name: John
          last_name: Watson
16
Helen