Enum

enum キーワードを使用して、リクエストパラメータまたはモデルプロパティの可能な値を指定できます。たとえば、

1
GET /items?sort=[asc|desc]

の並べ替えパラメータは、次のように記述できます。

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

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

1
enum:
2
  - asc
3
  - desc

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

1
type: string
2
enum:
3
  - asc
4
  - desc
5
description: >
6
  Sort order:
7
   * asc - Ascending, from A to Z.
8
   * desc - Descending, from Z to A.

再利用可能な Enum

再利用可能な enum 定義は、OpenAPI 3.0 でサポートされています。

Swagger 2.0 には再利用可能な enum の組み込みサポートはありませんが、ツールが YAML アンカーをサポートしている場合、YAML アンカーを使用して YAML で定義できます。アンカーは YAML の便利な機能で、&anchor-name でキーをマークし、さらに下で *anchor-name を使用してそのキーの値を参照できます。これにより、YAML ファイル全体でコンテンツを簡単に複製できます。

注：アンカー (&) は、使用する前に定義する必要があります。

1
definitions:
2
  Colors:
3
    type: string
4
    enum: &COLORS
5
      - black
6
      - white
7
      - red
8
      - green
9
      - blue
10
    # OR:
11
    # enum: &COLORS [black, white, red, green, blue]
12

13
paths:
14
  /products:
15
    get:
16
      parameters:
17
        - in: query
18
          name: color
19
          required: true
20
          type: string
21
          enum: *COLORS
22
      responses:
23
        200:
24
          description: OK

ツールの YAML パーサーが YAML マージキー (<<) をサポートしている場合、このトリックを使用して型と enum 値の両方を参照できます。

1
definitions:
2
  Colors: &COLORS
3
    type: string
4
    enum: [black, white, red, green, blue]
5
paths:
6
  /products:
7
    get:
8
      parameters:
9
        - in: query
10
          name: color
11
          required: true
12
          <<: *COLORS
13
      responses:
14
        200:
15
          description: OK

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