列挙型

OAS 2 このページはOpenAPI Specification ver. 2（旧Swagger）に適用されます。最新バージョンについては、OpenAPI 3のページをご覧ください。

列挙型

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

GET /items?sort=[asc|desc]

次のように記述できます

paths:
  /items:
    get:
      parameters:
        - in: query
          name: sort
          description: Sort order
          type: string
          enum: [asc, desc]

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

          enum:
            - asc
            - desc

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

          type: string
          enum:
            - asc
            - desc
          description: >
            Sort order:
             * asc - Ascending, from A to Z.
             * desc - Descending, from Z to A.

再利用可能な列挙型

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

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

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

definitions:
  Colors:
    type: string
    enum: &COLORS
      - black
      - white
      - red
      - green
      - blue
    # OR:
    # enum: &COLORS [black, white, red, green, blue]

paths:
  /products:
    get:
      parameters:
        - in: query
          name: color
          required: true
          type: string
          enum: *COLORS
      responses:
        200:
          description: OK

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

definitions:
  Colors: &COLORS
    type: string
    enum: [black, white, red, green, blue]
paths:
  /products:
    get:
      parameters:
        - in: query
          name: color
          required: true
          <<: *COLORS
      responses:
        200:
          description: OK

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