コンテンツにスキップ

例の追加

パラメータ、プロパティ、およびオブジェクトに例を追加することで、Web サービスの OpenAPI Specification をより明確にすることができます。例は、API を何らかの方法で処理するツールやライブラリによって読み取ることができます。たとえば、API モックツールはサンプル値を使用してモックリクエストを生成できます。オブジェクト、個々のプロパティ、および操作パラメータの例を指定できます。例を指定するには、example または examples キーを使用します。詳細は以下を参照してください。

Swagger UI ユーザーへの注意: 複数の examples のサポートは、Swagger UI 3.23.0 および Swagger Editor 3.6.31 以降で利用可能です。

注意: 例の値とデフォルトの値を混同しないでください。例は値がどうあるべきかを示します。デフォルト値は、クライアントが値を提供しない場合にサーバーが使用する値です。

パラメータの例

以下はパラメータ値の例です。

1
parameters:
2
  - in: query
3
    name: status
4
    schema:
5
      type: string
6
      enum: [approved, pending, closed, new]
7
      example: approved # Example of a parameter value

パラメータの複数の例

1
parameters:
2
  - in: query
3
    name: limit
4
    schema:
5
      type: integer
6
      maximum: 50
7
    examples: # Multiple examples
8
      zero: # Distinct name
9
        value: 0 # Example value
10
        summary: A sample limit value # Optional description
11
      max: # Distinct name
12
        value: 50 # Example value
13
        summary: A sample limit value # Optional description

ご覧のとおり、各例にはそれぞれ異なるキー名があります。また、上記のコードでは、オプションのsummaryキーを説明と共に使用しました。注：指定するサンプル値は、パラメータのデータ型と一致する必要があります。

リクエストとレスポンスボディの例

リクエストボディ内のexampleキーワードの例を次に示します

1
paths:
2
  /users:
3
    post:
4
      summary: Adds a new user
5
      requestBody:
6
        content:
7
          application/json:
8
            schema: # Request body contents
9
              type: object
10
              properties:
11
                id:
12
                  type: integer
13
                name:
14
                  type: string
15
              example: # Sample object
16
                id: 10
17
                name: Jessica Smith
18
      responses:
19
        "200":
20
          description: OK

上記のコードでは、exampleがschemaの子であることに注意してください。schemaがcomponentsセクションで定義された何らかのオブジェクトを参照している場合、exampleをメディアタイプキーワードの子にする必要があります。

1
paths:
2
  /users:
3
    post:
4
      summary: Adds a new user
5
      requestBody:
6
        content:
7
          application/json: # Media type
8
            schema: # Request body contents
9
              $ref: "#/components/schemas/User" # Reference to an object
10
            example: # Child of media type because we use $ref above
11
              # Properties of a referenced object
12
              id: 10
13
              name: Jessica Smith
14
      responses:
15
        "200":
16
          description: OK

これは、$refがその横にあるすべての兄弟を上書きするためです。必要に応じて、複数の例を使用できます。

1
paths:
2
  /users:
3
    post:
4
      summary: Adds a new user
5
      requestBody:
6
        content:
7
          application/json: # Media type
8
            schema: # Request body contents
9
              $ref: "#/components/schemas/User" # Reference to an object
10
            examples: # Child of media type
11
              Jessica: # Example 1
12
                value:
13
                  id: 10
14
                  name: Jessica Smith
15
              Ron: # Example 2
16
                value:
17
                  id: 11
18
                  name: Ron Stewart
19
      responses:
20
        "200":
21
          description: OK

レスポンスボディ内のexampleの例を次に示します。

1
responses:
2
  "200":
3
    description: A user object.
4
    content:
5
      application/json:
6
        schema:
7
          $ref: "#/components/schemas/User" # Reference to an object
8
        example:
9
          # Properties of the referenced object
10
          id: 10
11
          name: Jessica Smith

レスポンスボディの複数の例

1
responses:
2
  "200":
3
    description: A user object.
4
    content:
5
      application/json:
6
        schema:
7
          $ref: "#/components/schemas/User" # Reference to an object
8
        examples:
9
          Jessica:
10
            value:
11
              id: 10
12
              name: Jessica Smith
13
          Ron:
14
            value:
15
              id: 20
16
              name: Ron Stewart

注： レスポンスおよびリクエストボディの例は自由形式ですが、ボディスキーマと互換性があることが期待されます。

オブジェクトとプロパティの例

componentsセクションで、オブジェクトと個々のプロパティの例を指定することもできます。

  • プロパティレベルの例
1
components:
2
  schemas:
3
    User: # Schema name
4
      type: object
5
      properties:
6
        id:
7
          type: integer
8
          format: int64
9
          example: 1 # Property example
10
        name:
11
          type: string
12
          example: New order # Property example
  • オブジェクトレベルの例
1
components:
2
  schemas:
3
    User: # Schema name
4
      type: object
5
      properties:
6
        id:
7
          type: integer
8
        name:
9
          type: string
10
      example: # Object-level example
11
        id: 1
12
        name: Jessica Smith

スキーマとプロパティは単一のexampleをサポートしますが、複数のexamplesはサポートしないことに注意してください。

配列の例

個々の配列項目の例を追加できます

1
components:
2
  schemas:
3
    ArrayOfInt:
4
      type: array
5
      items:
6
        type: integer
7
        format: int64
8
        example: 1

または、複数の項目を含む配列レベルの例

1
components:
2
  schemas:
3
    ArrayOfInt:
4
      type: array
5
      items:
6
        type: integer
7
        format: int64
8
      example: [1, 2, 3]

配列にオブジェクトが含まれる場合、複数項目の例は次のように指定できます

1
components:
2
  schemas:
3
    ArrayOfUsers:
4
      type: array
5
      items:
6
        type: object
7
        properties:
8
          id:
9
            type: integer
10
          name:
11
            type: string
12
      example:
13
        - id: 10
14
          name: Jessica Smith
15
        - id: 20
16
          name: Ron Stewart

配列と配列項目は単一のexampleをサポートしますが、複数のexamplesはサポートしないことに注意してください。

XML および HTML データの例

JSONまたはYAML形式で表現できない例の値を記述するには、文字列として指定します

1
content:
2
  application/xml:
3
    schema:
4
      $ref: "#/components/schemas/xml"
5
    examples:
6
      xml:
7
        summary: A sample XML response
8
        value: "<objects><object><id>1</id><name>new</name></object><object><id>2</id></object></objects>"
9
  text/html:
10
    schema:
11
      type: string
12
    examples:
13
      html:
14
        summary: A list containing two items
15
        value: "<html><body><ul><li>item 1</li><li>item 2</li></ul></body></html>"

YAMLでの複数行文字列の記述に関する情報は、このStack Overflowの投稿で見つけることができます。https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines。

外部の例

何らかの理由でサンプル値を仕様に挿入できない場合（たとえば、YAMLまたはJSONに準拠していない場合）、externalValueキーワードを使用して例の値のURLを指定できます。URLは、リテラルの例のコンテンツ（オブジェクト、ファイル、画像など）を含むリソースを指す必要があります

1
content:
2
  application/json:
3
    schema:
4
      $ref: "#/components/schemas/MyObject"
5
    examples:
6
      jsonObject:
7
        summary: A sample object
8
        externalValue: "http://example.com/examples/object-example.json"
9
  application/pdf:
10
    schema:
11
      type: string
12
      format: binary
13
    examples:
14
      sampleFile:
15
        summary: A sample file
16
        externalValue: "http://example.com/examples/example.pdf"

例の再利用

一般的な例は、仕様のcomponents/examplesセクションで定義し、さまざまなパラメーター記述、リクエストおよびレスポンスボディ記述、オブジェクトおよびプロパティで再利用できます

1
    content:
2
      application/json:
3
        schema:
4
          $ref: '#/components/schemas/MyObject'
5
        examples:
6
          objectExample:
7
            $ref: '#/components/examples/objectExample'
8
    ...
9
    components:
10
      examples:
11
        objectExample:
12
          value:
13
            id: 1
14
            name: new object
15
          summary: A sample object

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