はじめに
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な設計を実現できます。