はじめに

API仕様書を書くときに「特定の決まった値しか受け付けない」ケースを記載する必要があることがあります。例えばユーザーの状態が「active / inactive」だけ、あるいはロールが「admin / user / guest」に限定されているような場面です。
本記事では、それをOpenAPIでどのように表現できるのか、そしてOpenAPI 3.0から可能になった共通化の方法を公式ドキュメントをもとにご紹介します。

OpenAPIで固定値を受け付ける方法

OpenAPIではenumを使うことで前述したような固定値の制約を表現することができます。

parameters:
  - in: query
    name: status
    schema:
      type: string
      enum: [active, inactive]

enumは上記のように配列のような形で指定します。1つ以上指定されている必要があるだけで、単一の値のみを指定することもできます。

parameters:
  - in: query
    name: status
    schema:
      type: string
      enum: [fixed-value]

enumは配列のような形ではなく、以下のように書くこともできます。チームのルールや可読性に合わせて使い分けます。

parameters:
  - in: query
    name: status
    schema:
      type: string
      enum:
        - active
        - inactive

さらに、説明を加える必要がある場合には description に記載します。

parameters:
  - in: query
    name: status
    schema:
      type: string
      enum:
        - active
        - inactive
    description: "ユーザの状態は active または inactive を指定してください"

OpenAPI 3.0では共通化ができる

OpenAPI 2.0では、enumを再利用することができませんでした。同じenumの中身でも繰り返し記述する必要があり、保守性に問題がありました。
しかし、OpenAPI 3.0では共通化してenumを再利用することができます。

components:
  schemas:
    UserStatus:
      type: string
      enum: [active, inactive]

paths:
  /users:
    get:
      parameters:
        - in: query
          name: status
          schema:
            $ref: '#/components/schemas/UserStatus'

nullの扱い

OpenAPI 3.0ではenumにnullを明示的に表記できます。

components:
  schemas:
    UserStatus:
      type: string
      nullable: true
      enum: [active, inactive, null]

この場合、nullable: true を指定する必要があり、また、enumに null を明記する必要があります。

OpenAPI 3.1以降では nullable は廃止され、次のように type に配列で null を含めて表現します。

type: [string, "null"]
enum: [active, inactive, null]

仕様書の全体例

openapi: 3.0.4
info:
  title: Sample API
  version: "1.0.0"

paths:
  /register:
    post:
      summary: Register a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [role]
              properties:
                role:
                  $ref: '#/components/schemas/UserRole'
      responses:
        "201":
          description: User registered
        "400":
          description: Invalid role

components:
  schemas:
    UserRole:
      type: string
      enum: [admin, user, guest]

このようにリクエストボディに組み込むと、クライアント側で「admin / user / guest 以外は送れない」ことが明示的になります。

まとめ

本記事では、OpenAPIにおけるenumの使い方と、OpenAPI 3.0から可能になった共通化について紹介しました。

enumを使うことで、APIが受け付ける値を特定の固定値に制約できます。これは仕様の明確化や入力チェックだけでなく、OpenAPI Generatorなどのクライアント生成ツールを使った場合にも型安全性を高めてくれます。

さらに、OpenAPI 3.0ではcomponents/schemasを利用してenumを共通定義として切り出せるようになり、複数のエンドポイントで同じ定義を再利用できるようになりました。これにより、保守性が大きく向上し、DRYな設計を実現できます。

参考

OpenAPI 2.0: https://swagger.io/docs/specification/v2_0/enums/
OpenAPI 3.0: https://swagger.io/docs/specification/v3_0/data-models/enums/