例の追加

API 仕様には、以下の例を含めることができます。

レスポンス MIME タイプ
スキーマ (データモデル)
スキーマ内の個々のプロパティ

例はツールやライブラリで使用できます。例えば、Swagger UI は入力スキーマの例に基づいてリクエストボディを自動入力し、一部の API モックツールは例を使用してモックレスポンスを生成します。

注: 例の値と default の値を混同しないでください。例は値がどのようなものであるべきかを説明するために使用されます。デフォルト値は、リクエストで値が提供されない場合にサーバーが使用するものです。

スキーマ例

example キーはスキーマの例を提供するために使用されます。例は個々のプロパティ、オブジェクト、およびスキーマ全体に対して指定できます。

プロパティの例

プロパティの例はインラインで指定できます。例の値はプロパティのタイプに準拠する必要があります。

1
definitions:
2
  CatalogItem:
3
    type: object
4
    properties:
5
      id:
6
        type: integer
7
        example: 38
8
      title:
9
        type: string
10
        example: T-shirt
11
    required:
12
      - id
13
      - title

プロパティまたはスキーマごとに複数の例の値はサポートされていません。つまり、次のようなものは使用できません。

1
title:
2
  type: string
3
  example: T-shirt
4
  example: Phone

オブジェクトの例

タイプオブジェクトのプロパティには、そのオブジェクトのプロパティを含む複雑なインライン例を含めることができます。例はオブジェクトスキーマに準拠する必要があります。

1
definitions:
2
  CatalogItem:
3
    type: object
4
    properties:
5
      id:
6
        type: integer
7
        example: 38
8
      title:
9
        type: string
10
        example: T-shirt
11
      image:
12
        type: object
13
        properties:
14
          url:
15
            type: string
16
          width:
17
            type: integer
18
          height:
19
            type: integer
20
        required:
21
          - url
22
        example:   # <-----
23
          url: images/38.png
24
          width: 100
25
          height: 100
26
    required:
27
      - id
28
      - title

配列の例

プリミティブの配列の例

1
definitions:
2
  ArrayOfStrings:
3
    type: array
4
    items:
5
      type: string
6
    example:
7
      - foo
8
      - bar
9
      - baz

同様に、オブジェクトの配列は次のように指定されます。

1
definitions:
2
  ArrayOfCatalogItems:
3
    type: array
4
    items:
5
      $ref: '#/definitions/CatalogItem'
6
    example:
7
      - id: 38
8
        title: T-shirt
9
      - id: 114
10
        title: Phone

スキーマ全体の例

例がスキーマに準拠している限り、example はスキーマ全体（すべてのネストされたスキーマを含む）に指定できます。

1
definition:
2
  CatalogItem:
3
    type: object
4
    properties:
5
      id:
6
        type: integer
7
      name:
8
        type: string
9
      image:
10
        type: object
11
        properties:
12
          url:
13
            type: string
14
          width:
15
            type: integer
16
          height:
17
            type: integer
18
    required:
19
      - id
20
      - name
21
    example:   # <----------
22
      id: 38
23
      name: T-shirt
24
      image:
25
        url: images/38.png
26
        width: 100
27
        height: 100

レスポンス例

Swagger では、レスポンスレベルで例を許可しており、各例は操作によって返される特定の MIME タイプに対応します。例えば、application/json の例と、text/csv の例などです。各 MIME タイプは、操作の produces 値のいずれかである必要があります。これは明示的であるか、グローバルスコープから継承されたものです。

1
produces:
2
  - application/json
3
  - text/csv
4
responses:
5
  200:
6
    description: OK
7
    examples:
8
      application/json: { "id": 38, "title": "T-shirt" }
9
      text/csv: >
10
        id,title
11
        38,T-shirt

すべての例は自由形式であり、その解釈はツールとライブラリに委ねられています。

JSON と YAML の例

JSON と YAML は互換性があるため（YAML は JSON のスーパーセット）、どちらも JSON 構文または

1
examples:
2
  application/json:
3
    {
4
      "id": 38,
5
      "title": "T-shirt"
6
    }

YAML 構文を使用して指定できます。

1
examples:
2
  application/json:
3
    id: 38
4
    title: T-shirt
5
    image:
6
      url: images/38.png

XML の例

XML レスポンスの例には特定の構文はありません。しかし、レスポンスの例は自由形式であるため、希望する任意の形式、またはツールでサポートされている形式を使用できます。

1
examples:
2
  application/xml: '<users><user>Alice</user><user>Bob</user></users>'
3

4
examples:
5
  application/xml:
6
    users:
7
      user:
8
        - Alice
9
        - Bob
10

11
examples:
12
  application/xml:
13
    url: http://myapi.com/examples/users.xml

または、上記で説明したように、レスポンススキーマで例の値を指定することもできます。

テキストの例

すべてのレスポンス例は自由形式であるため、ツールやライブラリでサポートされている任意の形式を使用できます。例えば、次のようなもの

1
examples:
2
  text/html: '<html><body><p>Hello, world!</p></body></html>'
3
  text/plain: Hello, world!

YAML で複数行の文字列を記述する方法については、Stack Overflow のこの記事も参照してください。

例の優先順位

異なるレベル（プロパティ、スキーマ、レスポンス）に複数の例がある場合、仕様を処理するツールは上位レベルの例を使用します。つまり、優先順位は次のとおりです。

レスポンスの例
スキーマの例
オブジェクトと配列プロパティの例
アトミックプロパティの例と配列項目の例

例と $ref

OpenAPI 2.0 の example および examples キーワードはインラインの例を必要とし、$ref をサポートしていません。例の値はそのまま表示されるため、$ref は $ref という名前のオブジェクトプロパティとして表示されます。

OpenAPI 3.0 では例の参照がサポートされています。

お探しのものが見つかりませんでしたか？コミュニティに質問する
間違いを見つけましたか？お知らせください