Enum

enumキーワードを使用して、リクエストパラメータまたはモデルプロパティの可能な値を指定できます。例えば、GET /items?sort=[asc|desc]のソートパラメータは次のように記述できます。

1
paths:
2
  /items:
3
    get:
4
      parameters:
5
        - in: query
6
          name: sort
7
          description: Sort order
8
          schema:
9
            type: string
10
            enum: [asc, desc]

YAMLでは、enum値を1行に1つずつ指定することもできます。

1
enum:
2
  - asc
3
  - desc

enum内のすべての値は、指定されたtypeに準拠する必要があります。enum項目に説明を指定する必要がある場合は、パラメータまたはプロパティのdescriptionでこれを行うことができます。

1
parameters:
2
  - in: query
3
    name: sort
4
    schema:
5
      type: string
6
      enum: [asc, desc]
7
    description: >
8
      Sort order:
9
       * `asc` - Ascending, from A to Z
10
       * `desc` - Descending, from Z to A

Nullable enums

nullableなenumは次のように定義できます。

1
type: string
2
nullable: true  # <---
3
enum:
4
  - asc
5
  - desc
6
  - null        # <--- without quotes, i.e. null not "null"

nullはenum値のリストに明示的に含める必要があることに注意してください。nullable: trueだけでは、ここでは十分ではありません。

Reusable enums

OpenAPI 3.0では、操作パラメータとデータモデルの両方でschemaを使用するため、データ型を簡単に再利用できます。再利用可能なenumはグローバルなcomponentsセクションで定義し、他の場所から$refを介して参照できます。

1
paths:
2
  /products:
3
    get:
4
      parameters:
5
        - in: query
6
          name: color
7
          required: true
8
          schema:
9
            $ref: "#/components/schemas/Color"
10
      responses:
11
        "200":
12
          description: OK
13
components:
14
  schemas:
15
    Color:
16
      type: string
17
      enum:
18
        - black
19
        - white
20
        - red
21
        - green
22
        - blue

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