メインコンテンツまでスキップ

OpenAPI: 3.1 で仕様を書いて Swagger UI で読む

エラーの設計の章までで、注文の API のエンドポイント・表現・誤りの応答を決め、サンプルリポジトリの docs/api-design/ に文書として置きました。この章では、決めたものを OpenAPI 3.1 の仕様に書きます。

仕様はサンプルリポジトリの openapi/openapi.yaml に置きました。設計の文書と仕様が食い違わないことをテストで確かめ、書いた仕様を Swagger UI で読みます。仕様の検査 (lint) とモックは、仕様の lint と モック の章で扱います。

API の仕様書の役割​

メソッドとステータスコードの章で動かした商品のサーバーは、何を受け付けて何を返すかが、コードの中にしか書いてありませんでした。利用者がそれを知るには、コードを読むか、呼んで試すしかありません。API の仕様書は、この約束をコードの外に、決まった形で書いたものです。

OpenAPI Specification (OAS) は、HTTP の API に対して、プログラミング言語に依存しない標準のインターフェースを定めます。人とコンピュータの両方が、ソースコードや文書を見たり通信を調べたりせずに、サービスの機能を見つけて理解できるようにするためのものです (OAS 3.1.2 の Introduction)。OpenAPI で書いた仕様は、API を表示する文書の生成、各言語のサーバーとクライアントのコードの生成、テストの道具などに使えます。

このガイドでは、仕様を道具に読ませます。この章の Swagger UI は仕様を画面で見せ、次の章の Redocly CLI は仕様を検査し、その次の章の Prism は仕様からモックを動かします。同じ章で、API を手で呼ぶ Bruno にも仕様を読み込ませます。第 2 部では、サーバーの実装が同じ仕様を読んでリクエストを確かめます。design-first では、1 つの仕様を、人が読む文書と道具が読む入力の両方に使います。

OpenAPI と Swagger の名前​

OpenAPI と Swagger は、同じものを指すように使われることがありますが、今は別のものの名前です。

OpenAPI Specification は、名前を変えた Swagger 2.0 の仕様にもとづいていて、その仕様は SmartBear Software が 2015 年に寄贈したものです (OpenAPI Initiative の FAQ)。寄贈の後、仕様は 2016 年に独立したプロジェクトになり、Linux Foundation の共同プロジェクトである OpenAPI Initiative が監督しています。

Swagger は、OpenAPI Specification を軸にしたオープンソースの道具の集まりの名前として残りました。Swagger UI は、その 1 つで、OpenAPI の定義を対話のできる文書として表示します (swagger.io の説明)。このガイドでは、仕様の形式を OpenAPI、画面の道具を Swagger UI と呼び分けます。

3.0・3.1・3.2 と、3.1 を選ぶ理由​

OAS の版は major.minor.patch の形で、major.minor (たとえば 3.1) が機能の集まりを決めます。patch の版は仕様の文書の誤りを直したり説明を明確にしたりするもので、機能は変えません。道具は patch の版を考慮すべきでない (SHOULD NOT) とされ、仕様はその例として 3.1.0 と 3.1.1 を区別しないことを挙げています (OAS 3.1.2 の 4.1 節)。

この章を書いた時点の各系列の最新の版は、3.0.4・3.1.2・3.2.1 です。このガイドに関わる 3.0 と 3.1 の違いは、スキーマの書き方にあります。3.1 の Schema Object は JSON Schema Draft 2020-12 の上位集合で (OAS 3.1.2 の 4.8.24 節)、3.0 の独自の書き方 (null を許すことを表す nullable など) をやめ、JSON Schema と同じ書き方にそろえました。

3.2 は、3.1 に機能を足した版です。タグの入れ子 (3.2 の発表)、HTTP の QUERY メソッド (同)、Server-Sent Events のようなストリームの 1 件ずつの形を書く itemSchema (同) などが入りました。

このガイドは 3.1 で書きます。理由は、使う道具がそろって 3.1 を読めることです。Swagger UI 5.34.1 の README の互換表は 3.1.0〜3.1.2 と 3.2.0 を挙げ (Compatibility)、Redoc も 3.2・3.1・3.0 に対応するとしています (Redoc の features)。一方、モックの Prism の README が対応する仕様に挙げるのは OpenAPI v3.1・v3.0・v2.0 で、3.2 は挙げていません (Prism の README)。3.2 で足された機能のうち、このガイドで使う場面のあるものは、第 8 部でまとめて扱います。

文書の openapi には、3.1 の系列の最新の 3.1.2 を書きました。このガイドで使う Swagger UI 5.34.1・Redocly CLI 2.72.1・Prism 5.16.0 は、どれもこの値の文書を読みました。

文書の構造​

仕様のファイルの先頭から、paths の始まりまでを見ます。

openapi: 3.1.2
info:
title: 注文 API
version: 0.1.0
description: |
EC の注文システムの API。注文する・注文を確かめるの 2 つの操作を持つ。

- 認証は無い。注文 ID を知っていれば、その注文を読める
- 応答には後からキーを足す。クライアントは、知らないキーを無視する
- 誤りの応答は、`Accept` に関わらず問題の詳細 (`application/problem+json`、RFC 9457) で返す。クライアントには `Accept: application/json, application/problem+json` を送ることを勧める
- 操作の外の失敗も問題の詳細で返す。エンドポイントの一覧に無いパスは 404、パスはあるがそのパスで受け付けないメソッドは 405 (`Allow` にそのパスで受け付けるメソッドを並べる)
- ここに書いていないステータスコード (中継の部品が返すものなど) も返りうる
license:
name: MIT
identifier: MIT
tags:
- name: orders
description: 注文
paths:
/orders:
# ...
components:
schemas:

OpenAPI の文書は、それ自体が 1 つの JSON のオブジェクトで、JSON でも YAML でも書けます (4.2 節)。このガイドは、コメントを書けて、文字列を引用符で囲まずに済む YAML で書きます。最上位のフィールドは次のとおりです。

フィールド中身
openapi文書が使う OAS の版 (必須)
infoAPI の題名・文書の版・説明・ライセンス。title と version が必須
tags操作をまとめるタグの一覧と、その説明
pathsパスごとの操作
components文書の中で使い回す部品 (スキーマ・応答・例など)

info.version は、この仕様の文書の版です。OAS の版とも、記述する API の版とも別のものです (Info Object)。最初の版として 0.1.0 を書きました。

servers と security は書いていません。servers は API のサーバーの URL の一覧で、省くと URL が / のサーバー 1 つを書いたのと同じになります (4.8.1.1 節の servers)。この章ではまだ API のサーバーもモックも動かしていないので、書く URL がありません。security は認証の仕組みを宣言するフィールドで、1 周目の API は認証を持たないので書きません。認証は第 5 部で足します。

info.description には、どの操作にも書けない約束を箇条で書きました。応答のキーが増えること、誤りの応答の形、操作の外の失敗 (エンドポイントの一覧に無いパスの 404 と、受け付けないメソッドの 405) です。405 と Allow は、パスと操作を単位に書く OpenAPI の形では、どの操作の応答にも置き場がありません。

$ref と components​

仕様の中の同じものを何か所でも使うときは、components に名前を付けて 1 回だけ書き、使う所から $ref で指します。この後の例はどれもこの書き方を使うので、先に読み方を説明します。

components:
schemas:
OrderId:
type: string
description: サーバーが作る注文 ID。クライアントは中身を読まず、文字列のまま使う。
ProductId:
type: string
minLength: 1
description: 商品 ID。クライアントは中身を読まず、文字列のまま使う。
ContactEmail:
type: string
format: email
description: 連絡先メールアドレス。
Quantity:
type: integer
format: int64
minimum: 1
maximum: 9007199254740991
description: 数量。
Amount:
type: integer
format: int64
minimum: 0
maximum: 9007199254740991
description: 消費税を含んだ円の整数。

components に置いたものは、外から参照されない限り API に何の影響もありません (Components Object)。使う所には、$ref: '#/components/schemas/Quantity' のように、文書の中の位置を書きます。# は「この文書」を、その後ろの /components/schemas/Quantity は文書の中の位置を表します。

$ref の扱いは、スキーマの中か外かで違います。スキーマの外 (応答や例を指す所) の $ref は Reference Object です。隣に書けるのは summary と description だけで、ほかのプロパティを足しても無視されます。この 2 つは、既定では参照先の同じフィールドを上書きすべき (SHOULD) とされ、参照先の型がそのフィールドを持たなければ効果がありません (Reference Object)。スキーマの中の $ref は JSON Schema 2020-12 のキーワードで、同じオブジェクトに $ref と別のキーワードを並べて書けます (JSON Schema Core の 8.2.3.1 節)。この仕様では、スキーマの中の $ref の隣には description だけを置き、その場の意味を書き足します。単価と合計と消費税額は、どれも Amount を指しながら、それぞれの説明を持ちます。

操作と operationId​

paths の下には、パスごとに Path Item Object を書き、その中の get・post などのフィールドに、そのメソッドの操作 (Operation Object) を書きます (Path Item Object)。注文するの操作は次のとおりです。

paths:
/orders:
post:
tags: [orders]
operationId: placeOrder
summary: 注文する
description: 商品と数量の組と連絡先メールアドレスを受け取り、注文を受付の状態で作る。商品の今の価格を単価として注文明細に写し、合計と消費税額を求め、在庫を引き当てる。
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PlaceOrderRequest'
examples:
place-order-request:
$ref: '#/components/examples/place-order-request'
responses:
# ...
/orders/{orderId}:

operationId は操作の名前で、API に書いたすべての操作の中で一意でなければなりません (MUST)。道具やライブラリが操作を見分けるのに使うことがあるので、一般的なプログラミングの命名の決まりに従うことが勧められています (operationId)。リソースの設計の章で対応表 (docs/api-design/operations.yaml) に書いた placeOrder と getOrder を、そのまま使いました。第 2 部では、サーバーの実装がこの名前で操作を受け持つ関数を探します。

summary は操作の短い要約で、ユースケースの名前 (注文する・注文を確かめる) にしました。description は操作の振る舞いの詳しい説明です。tags は操作を表示の上でまとめる名前で、Swagger UI はタグごとに操作を並べます (Operation Object の tags)。1 周目の操作は注文の 2 つだけなので、タグも orders の 1 つです。

操作を対応表と照らすテスト​

仕様の操作の名前は、対応表から写したものです。片方だけを直すと食い違うので、この章で足したテスト (test/openapi.test.ts) で照らします。

照らすのは、名前だけではありません。仕様の操作を「メソッド パス operationId」の組 (POST /orders placeOrder など) にして、対応表の組と集合で比べます。名前の集合だけを比べると、placeOrder を PUT /orders に置いた仕様でも通ってしまうからです。組で比べると、メソッドやパスがずれた仕様も、対応表に無い操作を足した仕様も落ちます。Path Item に操作でない知らないキーや、operationId の無い操作があるときは、それを数えずに通すことはせず、テストを落とします。

パスのパラメータ​

注文を確かめるのパス /orders/{orderId} の {orderId} は、パスのテンプレートの式です。パスの中のテンプレートの式は、どれもパスのパラメータに対応しなければなりません (MUST。3.5 節)。

/orders/{orderId}:
parameters:
- name: orderId
in: path
required: true
description: 注文するの応答の `orderId` を、そのまま入れる。注文 ID の形でない値も、その注文 ID の注文が無いものとして 404 になる。
schema:
$ref: '#/components/schemas/OrderId'
example: 01a194b4-978e-7c3a-9f21-6d4b8e2a1c05
get:
tags: [orders]
operationId: getOrder
summary: 注文を確かめる
description: 注文 ID の注文の、状態・注文日時・注文明細・合計・消費税額・連絡先メールアドレスを返す。

Parameter Object の in は、パラメータの場所を query・header・path・cookie のどれかで表します (in)。in が path なら、name はパスのテンプレートの式と同じ名前にし (name)、required は必ず書いて true にしなければなりません (MUST。required)。Path Item の parameters に置いたパラメータは、そのパスの下のすべての操作に当たります (parameters)。

注文 ID のスキーマには、形 (format: uuid や正規表現の pattern) を書きませんでした。理由は 2 つあります。1 つは、表現の設計の章で、クライアントは ID の中身を読まずに文字列のまま使うと決めたことです。Zalando の指針も、識別子に使う UUID には format を付けるべきでない (should not) としています (規則 144)。もう 1 つは、エラーの設計の章で、大文字を含む注文 ID や UUID の形でない注文 ID を「その注文 ID の注文が無い」として 404 にすると決めたことです。パスの変数に形を書くと、仕様でリクエストを確かめる道具は、形の合わない注文 ID を 404 より先に入力の誤りとして断りえます。

リクエストの本文​

注文するのリクエストの本文は、requestBody に書きました (前の節の注文するの操作)。required: true は本文が必須であることを表し、書かないと既定は false です (required)。content のキーはメディアタイプで、その値に本文のスキーマと例を書きます (content)。キーを application/json だけにしたので、受け付ける本文はこのメディアタイプだけです。

本文のスキーマは PlaceOrderRequest で、次の節で読みます。

JSON Schema 2020-12 でスキーマを書く​

3.1 の Schema Object は JSON Schema 2020-12 の上位集合で、キーワードの意味は、特に断りが無い限り JSON Schema の定義に従います (4.8.24 節)。ここからは、表現の設計の章で決めた決まりを、どのキーワードで書いたかを順に見ます。

リクエストの形: type と required​

PlaceOrderRequest:
type: object
description: 注文するのリクエスト。ここに無いキーがあれば、注文を受け付けない (`/problems/invalid-request`)。
additionalProperties: false
required: [contactEmail, lines]
properties:
contactEmail:
$ref: '#/components/schemas/ContactEmail'
lines:
type: array
description: 注文明細。同じ商品の注文明細は 1 つまでで、サーバーが確かめる。
minItems: 1
maxItems: 100
items:
type: object
additionalProperties: false
required: [productId, quantity]
properties:
productId:
$ref: '#/components/schemas/ProductId'
quantity:
$ref: '#/components/schemas/Quantity'

type は値の型を、object・array・string・integer などで表します (type)。properties はオブジェクトのキーごとのスキーマで、required はオブジェクトが必ず持つキーの名前の並びです (required)。表現の設計の章で、1 周目のリクエストには省いてよいキーが無いと決めたので、どのキーも required に並べました。

数と配列の範囲​

注文明細の数は、minItems: 1 と maxItems: 100 で書きました。配列の大きさがそれぞれの値以上と以下なら妥当です (minItems・maxItems)。数量 (Quantity) と金額 (Amount) の範囲は、minimum と maximum で書きました。

数量と金額の上限の 9007199254740991 は、2 の 53 乗から 1 を引いた値です。表現の設計の章は、整数の範囲を API の仕様にどう書くかを、この章へ送っていました。JSON の数値を倍精度の浮動小数点数 (IEEE 754 binary64) で扱う実装は広く使われていて、そうした実装どうしで値が厳密に一致する整数は、絶対値がこの値以下のものです (RFC 8259 の 6 節)。表現の設計の章のテストも、数量と金額をこの範囲の整数として確かめています。そこで、この範囲を仕様の上限にしました。表現の決まりの表には、上限を書いていません。

同じ商品の注文明細を 2 つ以上置かない決まりは、スキーマで書けませんでした。JSON Schema の uniqueItems は配列の要素がすべて等しくないことを求めますが (uniqueItems)、2 つのオブジェクトが等しいのは、すべてのキーと値が等しいときです (4.2.2 節)。りんごの数量 2 の明細と数量 3 の明細は等しくないので、uniqueItems は 2 つを通します。この決まりは lines の description に書き、サーバーが確かめます。

format は既定では注釈​

format は、文字列や数値の意味の上の形 (メールアドレス・日時・64 ビットの整数など) を表すキーワードです。JSON Schema 2020-12 では、format は既定では注釈で、検証には使われません。実装は format を検証に使ってもよい (MAY) ものの、それを有効にするかを選ばせなければならず、既定では無効でなければなりません (MUST。7.2.1 節)。OpenAPI 3.1.2 も、format を既定で検証しない注釈として扱い、検証できるかは道具によって違うとしています (4.4.1 節)。

それでも format を書くのは、道具が値の種類を知るためです。整数については、Zalando の指針が、number と integer のプロパティにはいつも int32・int64 などの format を付けなければならない (MUST) としています。付けないと、クライアントが精度を誤って推し量り、値を意図せず変えてしまうからです (規則 171)。

数量と金額には int64 を付けました。int32 の範囲は 2,147,483,647 まで (Format Registry の int32) で、上の上限より狭いからです。このガイドで使う Prism 5.16.0 とテストの検証器 (Ajv に ajv-formats を足したもの) は、int32 を付けた数量の 2,147,483,648 を入力の誤りとして断りました。エラーの設計の章の失敗の一覧には、その失敗がありません。int64 の範囲は 2 の 53 乗を超えますが、Format Registry は 53 ビットの範囲の外の値を文字列で表すことを勧めています (Format Registry の int64)。maximum で 2 の 53 乗 − 1 に限ったので、この仕様の金額と数量は数値のまま運べます。

連絡先メールアドレスには format: email を、注文日時には format: date-time を付けました。どちらも、形を確かめるのはサーバーの仕事です。Prism 5.16.0 とテストの検証器は、この仕様の連絡先メールアドレスに、メールアドレスの形でない値を送ると断りました。2 つとも、taro@localhost のようにドメインに . の無いアドレスも断りました。どこまで厳しく確かめるかは道具ごとに違い、表現の設計の章のテストの確かめは、このアドレスを通します。注文日時は、さらに pattern で、表現の設計の章で決めた形 (末尾が Z、秒の小数が 3 桁) を書きました。date-time だけでは、+09:00 のようなオフセットや、桁の違う秒の小数も通るからです。

増えうる値と増えない値: examples と enum​

注文の表現の状態 (status) と、注文明細の税率 (taxRate) は、どちらも決まった値の中の 1 つを持ちます。この 2 つを、違う書き方にしました。

status:
type: string
description: 注文の状態の code。値は後から増えるので、クライアントは知らない値を受け取っても止まらないようにする。今の値は `PENDING` (受付) だけ。
examples: [PENDING]
placedAt:
type: string
format: date-time
pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$'
description: 注文日時。UTC で書き、末尾を `Z` にし、秒の小数を 3 桁にそろえる。

enum は値の並びで、インスタンスがそのどれかと等しいときだけ妥当になります (enum)。並べた値のほかは無いと宣言することになります。Zalando の指針は、enum を定義の上で閉じた集合とし、値を足すことを互換にできない変更として扱います。enum を使うのは、値を API の持ち主が完全に握っていて、将来のどの機能でも値が出そろっている場合だけにするよう勧めます。それ以外では、今分かっている値を examples に並べ、description の頭に [Extensible enum](…) の印を付けます (規則 112)。印の無い examples には、スキーマのほかの条件に合うどの値も来うると読む、としています。

状態は、後の周回で値が増えます (取り消しや支払い済み)。表現の設計の章で、クライアントは知らない値を受け取っても止まらないようにすると決めました。そこで状態は enum にせず、今の値を examples に並べ、値が増えることを description に書きました。Zalando の印は、その指針の中の約束を指す印なので付けず、値が増えることと、クライアントが知らない値で止まらないことを description の文で書きました。examples は値の見本を並べる JSON Schema のキーワードで、検証には使われません (9.5 節)。スキーマの中の例は、この examples で書くのが OAS の勧める形で、単数の example は古い版との互換のために残っているだけです (Working with Examples)。

taxRate:
type: integer
format: int32
enum: [8, 10]
description: 税率 (百分率)。標準税率は 10、軽減税率は 8。

税率は enum: [8, 10] で閉じました。ドメインモデルの章で、税率は 8% か 10% のどちらかという不変条件を決め、表現の設計の章でも 8 か 10 の整数で持つと決めたからです。税率が増えるのは、法令が変わり、ドメインモデルの不変条件から直すときです。そのときは、この enum を広げる変更が、互換にできない変更として利用者に伝わります。

知らないキー: additionalProperties​

additionalProperties は、properties に無いキーの値に当てるスキーマです。false を書くと、properties に無いキーを持つオブジェクトは妥当でなくなります (additionalProperties)。書かなければ、どのキーも通ります。

この仕様は、リクエストのスキーマ (PlaceOrderRequest とその注文明細) にだけ additionalProperties: false を書き、応答のスキーマには書きませんでした。表現の設計の章で、リクエストに知らないキーがあれば注文を受け付けず、応答には後からキーを足すのでクライアントは知らないキーを無視する、と決めたからです。

リクエストのスキーマを閉じたのは、Zalando の指針から外れます。Zalando の規則 111 は、API の形式で additionalProperties を false にしてはならない (MUST NOT) とし、理由をオブジェクトを後から広げられなくなることに置いています (規則 111)。一方で、同じ指針の規則 109 は、ペイロードの知らない入力のフィールドを無視せず、400 で誤りを返すべき (SHOULD) としています (規則 109)。このガイドは、知らないキーを断る決まりを仕様に書くほうを選びました。閉じないと、仕様は「ほかのキーも受け付ける」と言うことになり、サーバーが断ることと食い違います。モックの章で、仕様からモックを動かしたときに、知らないキーを断る振る舞いも確かめられなくなります。

後からリクエストにキーを足すときも、閉じたスキーマは障りにならないと考えています。Zalando の規則 107 は、入力だけに使うスキーマには、省いてよいフィールドは足してよいが、必須のフィールドは足すべきでないとしています (規則 107)。この勧めのとおり省いてよいキーとして足せば、古いクライアントは足したキーを送らないまま通ります (この結論は指針の文でなく、このガイドの推論です)。

応答のスキーマを開いたままにしたのは、規則 111 のもう半分のとおりです。データを受け取るクライアントは、additionalProperties の宣言が無いオブジェクトを閉じたものとみなしてはならず、処理できないフィールドを無視しなければなりません (MUST)。

readOnly を使わない​

注文するのリクエストと注文の表現は、別のスキーマ (PlaceOrderRequest と Order) にしました。もう 1 つの書き方は、1 つの Order に両方のキーを置き、サーバーが決めるキー (注文 ID・単価など) に readOnly: true を付けるものです。

Order:
type: object
required: [orderId, contactEmail, lines]
properties:
orderId:
type: string
readOnly: true
contactEmail:
type: string
format: email

OAS 3.1.2 では、readOnly は注釈で、検証で読み書きの向きを見るかは道具が決めます (MAY)。読み取り専用のフィールドが送られてきたとき、サーバーはそれを無視しても、誤りにしてもよいとされています (readOnly と writeOnly の検証)。3.0 は、readOnly で必須のプロパティを、応答にだけ必須とすると定めていました (OAS 3.0.4)。3.1.2 は、readOnly の振る舞いが 3.0 から変わったことを断っています。上の例を、向きを見ない道具でリクエストの検証に使うと、required の orderId を注文するのリクエストにも求めます。

スタイルガイドの扱いも分かれます。Zalando は共通のスキーマに readOnly を付けることを勧め、送られてきた読み取り専用の値をサーバーが無視することも拒否することも認めています (規則 252)。Azure は、同じパスの POST のリクエストと応答に同じスキーマを使うことを求め (DO。Azure の指針)、読み取り専用のフィールドが今の値と一致しない限りリクエストを失敗させなければならない (MUST) としています (フィールドの可変性)。表現の設計の章で、リクエストに入った単価を無視するか断るかが分かれるのを避けるために別の形にしたので、この仕様もそれに従いました。

default を書かない​

default は、スキーマに結び付いた既定の値を示すキーワードです (9.2 節)。JSON Schema の非規範のガイドは、default は検証の途中で欠けた値を補うのには使われないと説明しています (Understanding JSON Schema)。値を補うのは、サーバーの仕事です。

quantity:
$ref: '#/components/schemas/Quantity'
default: 1

1 周目のリクエストには省いてよいキーが無いので、default を書く所がありません。後の周回で省いてよいキーを足すときは、表現の設計の章の決まりのとおり、省いたときの値をサーバーが補い、補った値を応答に入れます。仕様に default を書くのは、そのときにサーバーが補う値を利用者に知らせるためです。

注文の表現と応答​

注文の表現のスキーマは、リクエストと同じ書き方で、サーバーが決めるキーまで並べたものです。

Order:
type: object
description: 注文の表現。後からキーを足すので、クライアントは知らないキーを無視する。
required: [orderId, status, placedAt, contactEmail, lines, total, taxAmount]
properties:
orderId:
$ref: '#/components/schemas/OrderId'
status:
# ...
lines:
type: array
description: 注文明細。同じ商品の注文明細は 1 つまで。
minItems: 1
maxItems: 100
items:
$ref: '#/components/schemas/OrderLine'
total:
$ref: '#/components/schemas/Amount'
description: 合計。注文明細ごとの単価と数量の積の和。
taxAmount:
$ref: '#/components/schemas/Amount'
description: 消費税額。合計に含まれる消費税の額。

表現の決まりの「注文明細は 100 以下で、同じ商品の注文明細は 1 つまで」は、注文するのリクエストと注文の表現の両方に当たります。そこで、表現の lines にも maxItems と description を書きました。

注文するの成功の応答は、201 と Location ヘッダと注文の表現です。

responses:
'201':
description: 注文を受け付けた。本文は作った注文の表現。
headers:
Location:
description: 作った注文の URL。相対参照 (`/orders/{orderId}`) で返す。
required: true
schema:
type: string
format: uri-reference
example: /orders/01a194b4-978e-7c3a-9f21-6d4b8e2a1c05
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
order:
$ref: '#/components/examples/order'

responses は、ステータスコードを応答の記述に対応づけます。ステータスコードのキーは、JSON と YAML の両方で同じに読めるよう、引用符で囲みます (4.8.16.2 節)。応答の description は必須です (description)。すべてのステータスコードを書き尽くすことは求められませんが、成功の応答と分かっている誤りの応答は書くことが期待されています (Responses Object)。

応答のヘッダは headers に書きます。Location の値は 1 つの URI 参照で、相対参照なら対象の URI を基準に解決されます (RFC 9110 の 10.2.2 節)。リソースの設計の章で、Location には作った注文の URL を /orders/{orderId} の形で返すと決めました。スキームとホストを持たない相対参照なので、型は format: uri-reference の文字列にしました。Content-Type は headers に書かず、content のキー (application/json) で表します。headers に Content-Type を書いても無視されます (headers)。

例を仕様に入れる​

表現の設計の章とエラーの設計の章で examples/ に置いた JSON を、仕様の例にも入れました。Swagger UI は、仕様の例を応答の見本として画面に出します。モックの章の Prism は、仕様の例をモックの応答に使います。

examples:
place-order-request:
summary: りんご 2 個と保存容器 1 個を注文する
value:
contactEmail: taro.test@example.com
lines:
- productId: 01a0f4c2-c400-7a11-8b52-3c9d0e1f2a34
quantity: 2
- productId: 01a0f4c2-c7e8-7b22-a963-4dae1f203b45
quantity: 1

例は components/examples に、例のファイルと同じ名前 (拡張子を除く) を付けた Example Object で置き、Media Type Object の examples から $ref で指しました。Example Object は、例の値 (value) に短い説明 (summary) を付けたもので (Example Object)、Swagger UI は summary を例を選ぶ欄に出します。Media Type Object の例はスキーマに合い、メディアタイプの形に沿うべきとされています (Media Type Object)。

例の値は、仕様の中に写しました。Example Object には、値を外のファイルの URL で指す externalValue もありますが、このガイドで使う道具がその先のファイルを読むかは確かめていません。値を仕様の中に写せば、仕様を読める道具はどれも同じ例を読めます。写した値とファイルが食い違わないことは、テストで確かめます。

この章のテストは、例について次の 3 つを確かめます。

  • 仕様の名前付きの例は、どれも同じ名前の例のファイルと同じ値で、例のファイルは操作の外の失敗 (一覧に無いパスの 404 と受け付けないメソッドの 405) のものを除いてどれも仕様にある。同じ名前の例のファイルが 2 つのディレクトリにあれば落ちる
  • 仕様の名前付きの例は、置かれた場所のスキーマに合い、どれもどこかに置かれている。置かれた場所の例のキーは、指す例の名前と同じ
  • Location とパスの変数の例は、注文の例の注文 ID を指す

2 つ目は、仕様のスキーマで例を検証します。表現の設計とエラーの設計の章のテストは、例のファイルが docs/api-design/ の決まりに合うことを確かめています。2 つ目のテストが例を仕様のスキーマでも確かめるので、決まり・例・スキーマの 3 つがつながります。例が決まりに合っているのにスキーマに合わなければ、スキーマの写し方が誤っています。

誤りの応答を仕様に書く​

エラーの設計の章で決めた問題の詳細 (RFC 9457) を、スキーマにしました。RFC 9457 の付録 A には問題の詳細の JSON Schema が載っていますが、これは非規範で、本文と食い違えば本文が優先します (付録 A)。この仕様の Problem は、付録 A の書き方 (type は uri-reference の文字列、status は 100〜599 の整数) に、エラーの設計の章の決めを重ねたものです。たとえば、type・title・status はいつも入れます。detail は、題より詳しく言えることがあるときだけ入れます。instance は 1 周目は使いません。detail の minLength: 1 は、入れるなら空の文字列にしないことを表します。

Problem:
type: object
description: 問題の詳細 (RFC 9457)。クライアントは、知らないメンバーを無視する。
required: [type, title, status]
properties:
type:
type: string
format: uri-reference
description: 問題の型。自前の型は `/problems/` で始まる相対参照で、応答の文書の基準の URI に対して解決した URI が識別子になる (RFC 9457 の 3.1.1)。汎用の失敗は `about:blank`。
title:
type: string
description: 問題の型の題。
status:
type: integer
format: int32
minimum: 100
maximum: 599
description: 応答のステータスコードと同じ値。
detail:
type: string
minLength: 1
description: この発生の説明。クライアントは、読み取って処理を分けない。
InvalidRequestProblem:
description: 本文が JSON として読めないか、注文するのリクエストのスキーマに合わないか、同じ商品の注文明細が 2 つ以上ある。
allOf:
- $ref: '#/components/schemas/Problem'
- type: object
required: [errors]
properties:
type:
const: /problems/invalid-request
title:
const: Invalid request
status:
const: 400
errors:
# ...
PlaceOrderBadRequestProblem:
description: 注文するの 400 の本文。3 つの問題の型のどれか 1 つ。
oneOf:
- $ref: '#/components/schemas/InvalidRequestProblem'
- $ref: '#/components/schemas/UnknownProductProblem'
- $ref: '#/components/schemas/InsufficientInventoryProblem'

問題の型ごとのスキーマは、allOf で Problem とその型の部分を組み合わせました。allOf は、並べたスキーマのすべてに合うことを求めます (allOf)。型の部分では、type・title・status を const で 1 つの値に固め (const)、その型の拡張メンバー (errors など) を必須にしました。問題の型の使う場面は、型ごとのスキーマの description に書きました。エラーの設計の章で、問題の型の文書は仕様に置くと決めたので、ここがその置き場です。

注文するの 400 には、入力の誤り・登録されていない商品・在庫の不足の 3 つの型があります。そこで 400 の本文のスキーマを、3 つの型の oneOf (ちょうど 1 つに合う。oneOf) にしました。3 つの型は type の const が違うので、1 つの本文が 2 つの型に同時に合うことはありません。この章のテストは、3 つの例がどれも oneOf に合うことを確かめます。

'400':
description: |
注文を受け付けなかった。どの失敗かは `type` で見分ける。

- `/problems/invalid-request`: 本文の形か値の誤り
- `/problems/unknown-product`: 登録されていない商品がある
- `/problems/insufficient-inventory`: 在庫が数量より少ない商品がある

複数の失敗があるときは、本文の形・商品・在庫の順に確かめ、最初に当たった失敗だけを返す。
content:
application/problem+json:
schema:
$ref: '#/components/schemas/PlaceOrderBadRequestProblem'
examples:
invalid-request:
$ref: '#/components/examples/invalid-request'
unknown-product:
$ref: '#/components/examples/unknown-product'
insufficient-inventory:
$ref: '#/components/examples/insufficient-inventory'
'406':
$ref: '#/components/responses/NotAcceptable'
'415':
description: 本文のメディアタイプが `application/json` でない。
headers:
Accept:
description: 受け付ける本文のメディアタイプ。
required: true
schema:
type: string
example: application/json

誤りの応答の content のキーは application/problem+json です。問題の詳細を JSON の文書にしたときのメディアタイプで (RFC 9457 の 3 節)、エラーの設計の章で、誤りの応答は Accept に関わらずこの形で返すと決めました。415 の応答には、受け付けるメディアタイプを知らせる Accept ヘッダを書きました。

406 (Accept が application/json を受け入れない) と 500 (サーバーの予期しない誤り) は、2 つの操作のどちらも返します。この 2 つは components/responses に応答として 1 回書き、操作から $ref で指しました (Components Object の responses)。操作に固有の応答 (注文するの 400 と 415、注文を確かめるの 404) は、その操作の中に書いています。

仕様に書いたステータスコードを、エラーの設計の章の失敗の一覧と並べます。

失敗の一覧の操作仕様に書いた所
注文する (400・415)注文するの responses
注文を確かめる (404)注文を確かめるの responses
両方 (406・500)components/responses を、両方の操作の responses から指す
操作の外 (404・405)info.description の箇条

利用者が読む説明​

仕様の summary と description は、API を使ってアプリを作る利用者が読む文です。description には CommonMark (Markdown の 1 つの決まり) を使えるので、info.description と 400 の description では箇条を使いました。

説明の文は日本語で書き、語は用語集 (docs/glossary.yaml) にそろえました。operationId・タグの名前・部品の名前は、コードから使う名前なので英語です。誤りの応答の title と detail は、エラーの設計の章で決めたとおり英語のままです。

description には振る舞い (何を受け付け、何を返すか) を書き、設計の理由は書いていません。理由は docs/api-design/ の文書とこのガイドの記事が持ちます。仕様は、Diátaxis という文書の分け方で言う reference に当たります。Diátaxis は、文書を tutorials (学ぶ人を手引きする授業)・how-to guides (目標を果たす手順)・reference (仕組みの記述)・explanation (背景と理由) の 4 種類に分けます (Diátaxis)。reference の役目は、記述する製品を、できるだけ簡潔に整った形で記述することです (Reference)。手順や理由を reference に持ち込みたくなったら、それを書いた文書へリンクするよう勧めています (Describe and only describe)。

自動で作った reference だけで文書が足りると考えるソフトウェアの開発者が多すぎると、Diátaxis は指摘しています (Reference as description)。このガイドでは、設計の理由 (explanation) は docs/api-design/ が、注文を 1 件作って確かめるまでの手順 (how-to guides) はモックの章で書く docs/getting-started.md が受け持ちます。仕様からほかの文書へリンクするときは、externalDocs (External Documentation Object。url が必須) を使えます (External Documentation Object)。

Swagger UI で仕様を読む​

Swagger UI は、実装が無くても API のリソースを目で見て操作できるようにする道具で、OpenAPI の仕様から画面を作ります (Swagger UI の README)。npm には 3 つのパッケージがあり、このガイドは、サーバーから配るためのファイルをすべて含む swagger-ui-dist を使います (General)。

サンプルリポジトリでは、swagger-ui-dist 5.34.1 を devDependencies に固定で入れ、tools/swagger-ui/server.ts の小さなサーバーで配ります。このサーバーは、swagger-ui-dist の画面のファイルと、仕様のファイル (/openapi.yaml) と、読む仕様を決める初期化の script を配ります。Docker は使いません。コードは章末の「この章のサーバーのコード」にあります。

npm run docs:swagger で起動します。

npm run docs:swagger
結果
> rest-api-order@0.0.0 docs:swagger
> node tools/swagger-ui/server.ts

Swagger UI を http://localhost:3903 で起動しました

別の端末で、仕様のファイルが配られていることを確かめます。ステータスコードと Content-Type だけを出します。

curl -s -o /dev/null -w '%{http_code} %{content_type}\n' http://localhost:3903/openapi.yaml
結果
200 application/yaml

ブラウザで http://localhost:3903 を開くと、仕様の info と、タグごとの操作の一覧と、components/schemas の部品 (Schemas) が出ます。画面は Swagger UI 5.34.1 のものです。

Swagger UI の最初の画面。題名の注文 API の横に文書の版 0.1.0 と OAS 3.1 の印があり、info の説明、orders のタグの 2 つの操作、Schemas の一覧の順に並ぶ

操作の行を押すと、その操作が開きます。リクエストの本文の「Schema」を押すと、PlaceOrderRequest のキーと制約が出ます。必須のキーには赤い * が付き、lines の [1, 100] items は minItems と maxItems を、quantity の int64 は format を表します。Additional properties forbidden は、additionalProperties: false を書いたことを表します。

Swagger UI で POST /orders のリクエストの本文を Schema の表示にした画面。必須のキーに赤い星の印があり、lines の数の範囲、quantity の範囲と int64、Additional properties forbidden が出ている

応答の欄では、ステータスコードごとに description と例が出ます。名前付きの例が複数あるときは、例の summary を選ぶ欄が出ます。400 の欄では、入力の誤り・登録されていない商品・在庫の不足の 3 つの例を切り替えられます。

Swagger UI で POST /orders の 400 の応答を開いた画面。3 つの問題の型の説明の下に例を選ぶ欄があり、選んだ invalid-request の例の JSON が出ている

仕様のファイルは、サーバーがリクエストのたびに読み直します。openapi/openapi.yaml を直したら、ブラウザで読み込み直すと画面に反映されます。

Swagger UI には、画面からリクエストを送る Try it out の機能があります。この章では、送る先の API もモックもまだ無いので、初期化の script で supportedSubmitMethods を空にして、すべての操作で Try it out を出さないようにしました (Configuration)。モックの章で、Prism のモックへリクエストを送れるようにします。Swagger UI の文書は、CORS の対応が要らない場合を 2 つ挙げています。Swagger UI を API と同じサーバー (ホストとポートが同じ) で配るときと、API が必要な CORS のヘッダを付ける proxy の後ろにあるときです。それ以外では、画面から送るリクエストのために、API の側でも CORS を有効にする必要があります (CORS)。その設定も、モックの章で扱います。

Scalar と Redoc​

仕様から画面を作る道具は、Swagger UI のほかにもあります。Scalar は、OpenAPI の仕様から対話のできる API のリファレンスを作り、API を試す道具が付きます (Scalar の README)。Redoc は、OpenAPI などの定義から文書を作る道具で、既定では 3 列の画面 (左に検索とナビゲーション、中央に文書、右にリクエストと応答の例) になります (Redoc の README)。次の章では、Redocly CLI で仕様を検査し、同じ道具で Redoc の文書を作ります。

エディタで補完を出す​

仕様を手で書くときは、エディタにキーの補完と誤りの表示を出させると、綴りの誤りや置き場の誤りに書いている最中に気づけます。VS Code では、Red Hat の YAML の拡張がこれを受け持ちます。この拡張は、関連づけた JSON Schema にもとづいて YAML のキー・値・構造を補い (Ctrl+Space)、補完とホバーの中身をそのスキーマから作ります (vscode-yaml の README)。

サンプルリポジトリには、エディタの設定を置いていません。この拡張は、既定で SchemaStore のカタログを使い、よくあるファイル名に自動でスキーマを関連づけます (Associating schemas)。カタログは openapi.yaml というファイル名を OpenAPI のスキーマに結び (SchemaStore のカタログ)、openapi の値が 3.1 の文書には、OpenAPI Initiative が公開している 3.1 のスキーマを当てます (openapi-3.X.json)。このガイドでは、エディタで補完が出ることを試した結果は載せていません。拡張の README とカタログの記述から、ファイル名を openapi.yaml にしておけば関連づくと読めます。下のモードラインも、README の書き方から組み立てたもので、試してはいません。

ファイル名を変えたときは、ファイルの先頭にモードライン (決まった形のコメント) を書いて、スキーマを指定できます。モードラインは、ほかのどの関連づけより優先されます (Schema resolution priority)。URL は、SchemaStore が 3.1 の文書に当てるものと同じにしました。

# yaml-language-server: $schema=https://spec.openapis.org/oas/3.1/schema-base/2026-08-03
openapi: 3.1.2

エディタの検査は、書いている最中に気づくための補助です。仕様の検査は、次の章の lint でまとめて行います。

仕様と設計の文書を照らすテスト​

この章で足したテスト (test/openapi.test.ts) は、次の 7 つを確かめます。

  • 仕様の操作が、対応表の操作と、メソッド・パス・操作の名前の組で一致する
  • 表現の決まりのキーの表と、リクエストと表現のスキーマが、キーの名前と場所と必須で一致する
  • 仕様の名前付きの例が、同じ名前の例のファイルと同じ値で、操作の外の失敗を除くファイルがどれも仕様にある
  • 誤りの応答の決まりの失敗の一覧の、操作とステータスコードの組が、仕様のその操作の 4xx と 5xx の応答と一致する
  • 仕様の名前付きの例が、置かれた場所のスキーマに合い、どれもどこかに置かれている
  • リクエストのスキーマは知らないキーを断り、表現のスキーマは知らないキーを通す
  • Location とパスの変数の例が、注文の例の注文 ID を指す
npx vitest run test/openapi.test.ts
Test Files 1 passed (1)
Tests 7 passed (7)

2 つ目のテストは、キーの名前と場所と必須だけを比べ、型は比べません。型の決まりは、表現の決まりのキーの表 (「整数 (円)」など) と仕様のスキーマ (type: integer と minimum など) の 2 か所に並んでいます。どちらを元にしてもう片方を作るかは、次の章で、08〜10 章の決まりを API の設計のガイドラインにまとめるときに決めます。それまでは、表と仕様で書き方の違う所を、次の表で示しておきます。

キー表現の決まりの表の型仕様のスキーマ違い
orderId文字列 (UUIDv7)type: string だけ仕様は形を書かない。クライアントは中身を読まず、形の合わない注文 ID も 404 にするため
placedAt文字列 (UTC の日時)format: date-time と pattern表の形 (末尾が Z、秒の小数が 3 桁) を pattern で写した
status文字列 (状態の code)type: string と examples値が増えるので閉じない
contactEmail文字列 (メールアドレス)format: email形の確かめの厳しさは道具で違う。テストの検証器と Prism はドメインに . の無いアドレスを断り、表現の設計の章のテストは、空白と @ を含まない 1 文字以上の文字列を @ 1 つでつないだ形かだけを見る
quantity・金額整数 (1 以上)・整数 (円)format: int64 と minimum・maximum表には上限が無い。上限 (2 の 53 乗 − 1) は、この章で仕様に決めた

このテストは、キーの表から行を拾えないとき、その行を捨てずに落ちます。表の行の書き方を変えたのに、テストの拾い方を直し忘れると、キーが 1 つ抜けたまま一致を確かめてしまうからです。

コードは章末の「この章のテストのコード」にあります。

見直しの観点​

仕様を書いたら、次の観点で見直します。

  • 仕様の操作の名前・メソッド・パスが、対応表と同じか
  • リクエストのスキーマが、表現の決まりで受け付けないものを断るか (知らないキー・範囲の外の数・空の配列)
  • 応答のスキーマが、後から足すキーや値を通すか (閉じたオブジェクトや、増える値の enum が無いか)
  • 決まったけれどスキーマで書けないこと (同じ商品の注文明細の重なりなど) を、description に書いたか
  • 誤りの応答の例が、その応答のステータスコードと問題の型に合うか
  • description に、設計の理由や実装の詳細を書いていないか

選ばなかった案​

案選ばなかった理由
OpenAPI 3.2 で書くモックの Prism の README が対応する仕様に 3.2 を挙げていない。3.2 の機能を使う場面は第 8 部まで無い
状態を enum: [PENDING] にする値を足すたびに、互換にできない変更になる。表現の設計の章で、値が増えると決めた
税率を examples にして閉じない表現の設計の章とドメインモデルの不変条件で、8 か 10 と決めた
応答のスキーマも閉じる応答に後からキーを足すと、互換にできない変更になる
リクエストのスキーマを閉じない仕様が受け付けるものと、サーバーが受け付けるものが食い違う
数量に format: int32 を付けるこのガイドで使う Prism とテストの検証器が、失敗の一覧に無い上限 (2,147,483,647) で数量を断る
注文 ID に format: uuid か pattern を付けるクライアントは中身を読まない。形の合わない注文 ID も 404 にする決めと食い違う
1 つの Order に readOnly を付けてリクエストにも使う3.1 の readOnly は注釈で、読み書きの向きを見るかは道具が決める。読み取り専用の値を無視するか断るかも、サーバーごとに分かれる
問題の詳細を 1 つの Problem にまとめ、拡張メンバーをすべて並べるどの問題の型にどの拡張メンバーが入るかを、スキーマで表せない
例を externalValue で例のファイルから読ませる道具が外のファイルを読むかを確かめていない。値を仕様に写せば、仕様を読む道具はどれも同じ例を読める

実務で効く注意点​

format の検証は道具によって違う​

JSON Schema 2020-12 の既定では、format は検証に使われません。この章で format: email を書いた連絡先メールアドレスも、format を検証しない道具は、どんな文字列でも通します。同じ仕様から作ったモック・クライアントのコード・サーバーの検証が、メールアドレスの形について違う振る舞いをしうるということです。道具を選ぶときは、format を検証するか、どの format を検証するかを確かめます。道具に必ず確かめさせたい範囲は、minimum・maxItems・pattern のような検証のキーワードで書きます。

仕様が正しいことと、サーバーが仕様どおりに動くことは別​

この章のテストが確かめるのは、仕様と設計の文書と例が食い違わないことです。サーバーが仕様どおりに応答するかは、まだ何も確かめていません。仕様は、書いた後もサーバーの実装と離れていきえます。第 2 部では、サーバーの応答を仕様と照らすテストを足し、仕様と実装が離れたときに気づけるようにします。

まとめ​

  • OpenAPI は HTTP の API の仕様を、言語に依存しない形で書く標準です。Swagger は、その周りの道具の名前として残りました
  • このガイドは、使う道具がそろって読める 3.1 で書きます。openapi には 3.1.2 を書き、info.version は API の版でなく文書の版です
  • 使い回す部品は components に 1 回書き、$ref で指します。スキーマの中の $ref の隣には、別のキーワードを並べられます
  • 08〜10 章の決まりは、required・minItems・maximum・additionalProperties・enum・const・oneOf などのキーワードで書きました。同じ商品の注文明細の重なりのように、スキーマで書けない決まりは description に書きます
  • 値が増える状態は examples で開き、ドメインモデルが閉じた税率は enum で閉じました。リクエストのスキーマは閉じ、応答のスキーマは開いています
  • format は既定では注釈です。整数には精度を示す format を付け、確かめさせたい範囲は minimum と maximum で書きました
  • 仕様の操作・キー・例が、対応表・表現の決まり・例のファイルと食い違わないことをテストで確かめ、例を仕様のスキーマで検証します
  • 書いた仕様は Swagger UI で読みます。Try it out は、モックができてから使います

次に読む​

前の章は エラーの設計 です。

次章 仕様の lint では、Redocly CLI でこの仕様を検査し、API の設計のガイドラインを規則にして守らせます。

練習問題​

後の周回で、注文の状態に取り消し (CANCELLED) が加わります。状態を enum: [PENDING] で書いていたら、何が起きますか

解答例

enum: [PENDING] は、状態の値は PENDING だけだと宣言しています。仕様からクライアントのコードを生成する道具は、状態を PENDING だけを持つ型にしうるので、そのクライアントは CANCELLED を受け取ったときに型の誤りや検証の誤りで止まりえます。仕様の enum に CANCELLED を足すと、こうしたクライアントを作り直さなければ使えなくなるので、互換にできない変更になります。

この章では、状態を type: string と examples: [PENDING] で書き、値が増えることを description に書きました。クライアントは、知らない状態を受け取っても止まらない作りにしておきます (表現の設計の章の決まり)。CANCELLED を足すときは、examples に値を足し、取り消しの周回の要件の差分に書きます。

レビューで「数量に format: int32 を付けたほうが、クライアントが扱いやすい」と指摘されました。どう考えますか

解答例

int32 の範囲は 2,147,483,647 までです。この章のテストの検証器とモックの Prism は、int32 を付けた数量の 2,147,483,648 を入力の誤りとして断ります。エラーの設計の章の失敗の一覧には、2,147,483,648 のような数量を断る行がありません。2 の 53 乗 − 1 を超える数量は、表現の設計の章のテストの読みでは「整数」の型に合わない値で、失敗の一覧の「値が null か型が合わない」に当たります。この章で数量の上限を 2 の 53 乗 − 1 にしたのも、この読みに合わせたものです。int32 を付けると、仕様がこの上限より狭くなり、失敗の一覧に無い理由で数量を断ることになります。

数量に現実的な上限を設けたいなら、まず要件として決めます。ユースケースの手順 2 の確かめに上限を足し、エラーの設計の章の失敗の一覧の入力の誤りの行に加えてから、仕様の maximum を直します。その上限が int32 に収まるなら、そのときに format を int32 に変えられます。

この章のテストのコード​

仕様が、対応表・表現の決まり・例のファイルと食い違わないことを確かめるテストのコードです。読まなくても本文は追えます。

仕様を読む処理と、仕様のスキーマで値を検証する処理は、test/support/openapi.ts にまとめました。仕様の文書は JSON Schema ではない (openapi・paths などを持つ) ので、components/schemas だけを持つ文書に包んで検証器に登録しています。

/*
* 注文 API の仕様 (openapi/openapi.yaml) を読み、テストから使える形にする処理。
* 仕様のファイルの置き方を変えたら、読み方はここだけを直す。
*/
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { Ajv2020 } from 'ajv/dist/2020.js';
import type { ValidateFunction } from 'ajv/dist/2020.js';
import formats from 'ajv-formats';
import { parse } from 'yaml';

export function loadSpec(): unknown {
return parse(readFileSync(fileURLToPath(new URL('../../openapi/openapi.yaml', import.meta.url)), 'utf8'));
}

/**
* 仕様の components/schemas の部品を JSON Schema 2020-12 の検証器に登録し、部品の名前で検証の関数を返す。
* 仕様の文書は JSON Schema ではない (openapi・paths などを持つ) ので、components/schemas だけを持つ文書に包んで登録する。
* 部品どうしの '#/components/schemas/<名前>' の参照は、包んだ文書の中で解決する。format (email・date-time など) も検証する。
*/
export function schemaValidator(spec: unknown): (name: string) => ValidateFunction {
const schemas = (spec as { components?: { schemas?: unknown } }).components?.schemas;
if (typeof schemas !== 'object' || schemas === null) throw new Error('仕様に components/schemas が無い');
const ajv = new Ajv2020({ allErrors: true });
formats.default(ajv);
// 包んだ文書の最上位の components は、JSON Schema のキーワードでないことを検証器に知らせる。
ajv.addVocabulary(['components']);
ajv.addSchema({ $id: 'openapi.json', components: { schemas } });
return (name) => {
const validate = ajv.getSchema(`openapi.json#/components/schemas/${name}`);
if (validate === undefined) throw new Error(`仕様の components/schemas に ${name} が無い`);
return validate;
};
}
/*
* 注文 API の仕様 (openapi/openapi.yaml) が、対応表・表現の決まり・例のファイルと食い違わないことを確かめる。
* 仕様はこれらを写したものなので、片方だけを直すと、仕様と文書が別のことを言うようになるため。
*/
import { readdirSync, readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { expect, it } from 'vitest';
import { parse } from 'yaml';
import { loadSpec, schemaValidator } from './support/openapi.ts';

function read(path: string): string {
return readFileSync(fileURLToPath(new URL(`../${path}`, import.meta.url)), 'utf8');
}

function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}

/** 値の中の、名前で並ぶオブジェクト (paths・components の各部など)。無ければ空。 */
function entries(value: unknown): [string, unknown][] {
return isRecord(value) ? Object.entries(value) : [];
}

const spec = loadSpec();
const components = isRecord(spec) && isRecord(spec.components) ? spec.components : {};
const schemas = isRecord(components.schemas) ? components.schemas : {};
const namedExamples = isRecord(components.examples) ? components.examples : {};

/** '#/components/<種類>/<名前>' の参照なら名前を、そうでなければ undefined を返す。 */
function refName(value: unknown, kind: string): string | undefined {
if (!isRecord(value) || typeof value.$ref !== 'string') return undefined;
const prefix = `#/components/${kind}/`;
return value.$ref.startsWith(prefix) ? value.$ref.slice(prefix.length) : undefined;
}

/** スキーマの部品の参照なら、参照先の部品を返す。参照でなければ、そのまま返す。 */
function deref(value: unknown): unknown {
const name = refName(value, 'schemas');
return name === undefined ? value : schemas[name];
}

/**
* Path Item で操作を表すフィールド (OpenAPI 3.1 の HTTP のメソッド)。
* Path Item に書いてよい操作でないキー。ほかのキー ($ref を含む) は、操作を見落とさないよう誤りにする。
*/
const methods = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
const pathItemKeys = ['summary', 'description', 'servers', 'parameters'];

/** 仕様の操作を「メソッド パス operationId」の文にして返す。拾えないものは problems に入れる。 */
function operationsOf(problems: string[]): string[] {
const operations: string[] = [];
const paths = isRecord(spec) ? spec.paths : undefined;
for (const [path, item] of entries(paths)) {
for (const [key, operation] of entries(item)) {
if (!methods.includes(key)) {
if (!pathItemKeys.includes(key)) problems.push(`${path} の Path Item に、操作でない知らないキー ${key} がある`);
continue;
}
if (!isRecord(operation) || typeof operation.operationId !== 'string') {
problems.push(`${key.toUpperCase()} ${path} に operationId が無い`);
continue;
}
operations.push(`${key.toUpperCase()} ${path} ${operation.operationId}`);
}
}
return operations;
}

/** 表の本体の行 (見出しと区切りの行の次から、空行の前まで)。形の合わない行を数えられるよう、正規表現で拾う前の行を返す。 */
function tableLines(text: string, header: string): string[] {
const lines = text.split(/\r?\n/);
const start = lines.indexOf(header);
if (start < 0) return [];
const end = lines.findIndex((line, index) => index > start && line.trim() === '');
return lines.slice(start + 2, end < 0 ? undefined : end);
}

/** 行を pattern で拾い、拾えない行は problems に足す。拾えない行が黙って抜けないよう、形の確かめと一緒に行う。 */
function rows<T>(text: string, header: string, pattern: RegExp, toRow: (match: RegExpExecArray) => T, problems: string[]): T[] {
const lines = tableLines(text, header);
if (lines.length === 0) problems.push(`表 ${header} が無いか、行が無い`);
return lines.flatMap((line) => {
const match = pattern.exec(line);
if (match === null) {
problems.push(`表の行を拾えない: ${line}`);
return [];
}
return [toRow(match)];
});
}

it('仕様の操作が、対応表の操作と、メソッド・パス・操作の名前の組で一致する', () => {
const problems: string[] = [];
const operations = operationsOf(problems);
expect(problems).toEqual([]);
expect(operations.length).toBeGreaterThan(0);
const table: unknown = parse(read('docs/api-design/operations.yaml'));
const rowsOfTable = isRecord(table) && Array.isArray(table.operations) ? table.operations.filter(isRecord) : [];
const expected = rowsOfTable.map((row) => `${String(row.method)} ${String(row.path)} ${String(row.operationId)}`);
expect([...operations].sort()).toEqual([...expected].sort());
});

interface KeyRow {
key: string;
/** 最上位なら空文字列、配列の要素ならその配列のキー。 */
place: string;
inRequest: boolean;
inOrder: boolean;
}

const keyHeader = '| キー | 場所 | 語 | 型 | 注文するのリクエスト | 注文の表現 |';
const keyPattern = /^\| `([^`]+)` \| (?:最上位|`([^`]+)` の要素) \| [^|]+ \| [^|]+ \| (入れる|入れない) \| (入れる|入れない) \|$/;

/**
* キーの表の列と、その列のキーを持つスキーマの部品。表の型と仕様のスキーマのどちらを元にするかはまだ決めていないので、
* ここでは型を比べず、キーの名前・場所と、required (1 周目は省いてよいキーが無いので、入るキーはすべて必須) だけを比べる。
*/
const columns = [
{ column: 'inRequest', schema: 'PlaceOrderRequest' },
{ column: 'inOrder', schema: 'Order' },
] as const;

it('表現の決まりのキーの表と、リクエストと表現のスキーマが、キーの名前と場所と必須で一致する', () => {
const problems: string[] = [];
const keyRows = rows<KeyRow>(
read('docs/api-design/representation.md'),
keyHeader,
keyPattern,
(m) => ({ key: m[1], place: m[2] ?? '', inRequest: m[3] === '入れる', inOrder: m[4] === '入れる' }),
problems,
);
expect(problems).toEqual([]);
for (const { column, schema } of columns) {
const root = schemas[schema];
for (const place of [...new Set(keyRows.map((row) => row.place))]) {
const expected = keyRows.filter((row) => row[column] && row.place === place).map((row) => row.key).sort();
if (expected.length === 0) continue;
const where = place === '' ? `${schema}` : `${schema} の ${place} の要素`;
const target = place === '' ? root : deref(isRecord(root) && isRecord(root.properties) && isRecord(root.properties[place]) ? root.properties[place].items : undefined);
const properties = isRecord(target) && isRecord(target.properties) ? Object.keys(target.properties).sort() : [];
const required = isRecord(target) && Array.isArray(target.required) ? [...target.required].sort() : [];
expect(properties, `${where} の properties`).toEqual(expected);
expect(required, `${where} の required`).toEqual(expected);
}
}
});

/** 例のファイルのディレクトリ。仕様の名前付きの例は、このどちらかの同じ名前のファイルと同じ値にする。 */
const exampleDirs = ['examples/orders', 'examples/problems'];
const exampleFileList = exampleDirs.flatMap((dir) =>
readdirSync(fileURLToPath(new URL(`../${dir}/`, import.meta.url)))
.filter((name) => name.endsWith('.json'))
.map((name) => [name.replace(/\.json$/, ''), `${dir}/${name}`] as const),
);
const exampleFiles = new Map(exampleFileList);

const failureHeader = '| 操作 | 失敗 | ユースケース | 問題の型 | ステータスコード |';
const failurePattern = /^\| ([^|]+) \| [^|]+ \| [^|]+ \| `([^`]+)` \| (\d{3}) \|$/;

/**
* どの操作にも書けない失敗 (エンドポイントの一覧に無いパスの 404 と、受け付けないメソッドの 405) の例のファイル。
* 誤りの応答の決まり (problems.md) の失敗の一覧で操作が「操作の外」の行の型とステータスコードを、問題の型の表の例の列で引く。
*/
function outsideOperationExamples(problems: string[]): string[] {
const text = read('docs/api-design/problems.md');
const failures = rows(text, failureHeader, failurePattern, (m) => ({ operation: m[1].trim(), type: m[2], status: m[3] }), problems);
const types = rows(
text,
'| 型 | ステータスコード | 題 | 使う場面 | 拡張メンバー | 例 |',
/^\| `([^`]+)` \| (\d{3}) \| [^|]+ \| [^|]+ \| [^|]+ \| `([a-z-]+)\.json` \|$/,
(m) => ({ type: m[1], status: m[2], example: m[3] }),
problems,
);
return failures
.filter((failure) => failure.operation === '操作の外')
.flatMap((failure) => types.filter((type) => type.type === failure.type && type.status === failure.status).map((type) => type.example));
}

it('仕様の名前付きの例が、同じ名前の例のファイルと同じ値で、操作の外の失敗を除くファイルがどれも仕様にある', () => {
const problems: string[] = [];
const outside = outsideOperationExamples(problems);
// 2 つのディレクトリに同じ名前のファイルがあると、Map では後のほうだけが残り、前のほうを照らさない。
const names = exampleFileList.map(([name]) => name);
for (const name of names.filter((name, index) => names.indexOf(name) !== index)) problems.push(`例のファイル ${name}.json が 2 つのディレクトリにある`);
expect(problems).toEqual([]);
expect(outside.length).toBeGreaterThan(0);
for (const [name, example] of Object.entries(namedExamples)) {
const file = exampleFiles.get(name);
expect(file, `${name} の例のファイルが ${exampleDirs.join(' か ')} に無い`).toBeDefined();
expect(isRecord(example) ? example.value : undefined, `${name} の value`).toStrictEqual(JSON.parse(read(file ?? '')));
}
const expected = [...exampleFiles.keys()].filter((name) => !outside.includes(name)).sort();
expect(Object.keys(namedExamples).sort()).toEqual(expected);
});

// 失敗の一覧の操作の列は、対応表のユースケースの名前か、「両方」(すべての操作) か「操作の外」(どの操作にも書けない)。
it('失敗の一覧の操作とステータスコードの組が、仕様のその操作の 4xx と 5xx の応答と一致する', () => {
const problems: string[] = [];
const failures = rows(read('docs/api-design/problems.md'), failureHeader, failurePattern, (m) => ({ operation: m[1].trim(), status: m[3] }), problems);
const table: unknown = parse(read('docs/api-design/operations.yaml'));
const tableRows = isRecord(table) && Array.isArray(table.operations) ? table.operations.filter(isRecord) : [];
const paths = isRecord(spec) && isRecord(spec.paths) ? spec.paths : {};
for (const row of tableRows) {
const useCase = String(row.useCase);
const item = paths[String(row.path)];
const operation = isRecord(item) ? item[String(row.method).toLowerCase()] : undefined;
const inSpec = entries(isRecord(operation) ? operation.responses : undefined)
.map(([code]) => code)
.filter((code) => /^[45]/.test(code))
.sort();
const listed = [...new Set(failures.filter((failure) => failure.operation === useCase || failure.operation === '両方').map((failure) => failure.status))].sort();
if (inSpec.join() !== listed.join()) problems.push(`${useCase}: 仕様の応答は ${inSpec.join('・')}、失敗の一覧は ${listed.join('・')}`);
}
const known = [...tableRows.map((row) => String(row.useCase)), '両方', '操作の外'];
for (const failure of failures.filter((failure) => !known.includes(failure.operation))) problems.push(`失敗の一覧の操作 ${failure.operation} が、対応表のユースケースにも、両方・操作の外にも無い`);
expect(problems).toEqual([]);
expect(tableRows.length).toBeGreaterThan(0);
});

/**
* 操作の requestBody と応答 (部品の応答の参照もたどる) の Media Type Object を、置き場の名前とともに返す。
* components/responses に無い名前を指す応答の参照は、その応答の例を照らさずに抜けないよう、problems に足す。
*/
function mediaTypes(problems: string[]): { where: string; media: unknown }[] {
const responses = isRecord(components.responses) ? components.responses : {};
const found: { where: string; media: unknown }[] = [];
const paths = isRecord(spec) ? spec.paths : undefined;
for (const [path, item] of entries(paths)) {
for (const [method, operation] of entries(item).filter(([key]) => methods.includes(key))) {
const where = `${method.toUpperCase()} ${path}`;
const body = isRecord(operation) ? operation.requestBody : undefined;
for (const [type, media] of entries(isRecord(body) ? body.content : undefined)) {
found.push({ where: `${where} のリクエストの ${type}`, media });
}
for (const [code, response] of entries(isRecord(operation) ? operation.responses : undefined)) {
const name = refName(response, 'responses');
const resolved = name === undefined ? response : responses[name];
if (name !== undefined && !isRecord(resolved)) problems.push(`${where} の ${code} が、components/responses に無い ${name} を指す`);
for (const [type, media] of entries(isRecord(resolved) ? resolved.content : undefined)) {
found.push({ where: `${where} の ${code} の ${type}`, media });
}
}
}
}
return found;
}

it('仕様の名前付きの例が、置かれた場所のスキーマに合い、どれもどこかに置かれている', () => {
const validator = schemaValidator(spec);
const problems: string[] = [];
const used = new Set<string>();
for (const { where, media } of mediaTypes(problems)) {
const schema = refName(isRecord(media) ? media.schema : undefined, 'schemas');
if (schema === undefined) {
problems.push(`${where} の schema が components/schemas の部品の参照でない`);
continue;
}
const validate = validator(schema);
for (const [key, example] of entries(isRecord(media) ? media.examples : undefined)) {
const name = refName(example, 'examples');
const value = name === undefined ? undefined : namedExamples[name];
if (name === undefined || !isRecord(value)) {
problems.push(`${where} の例 ${key} が components/examples の例の参照でない`);
continue;
}
used.add(name);
if (key !== name) problems.push(`${where} の例のキー ${key} が、参照先の名前 ${name} と違う`);
if (!validate(value.value)) {
problems.push(`${where} の例 ${name} が ${schema} に合わない: ${JSON.stringify(validate.errors)}`);
}
}
}
for (const name of Object.keys(namedExamples)) {
if (!used.has(name)) problems.push(`例 ${name} がどこにも置かれていない`);
}
expect(problems).toEqual([]);
expect(used.size).toBeGreaterThan(0);
});

/*
* リクエストは、表で「入れる」としたほかのキーがあれば受け付けない (表現の決まりの形の節)。応答には後からキーを足し、
* クライアントは知らないキーを無視する。仕様のスキーマがこの 2 つを写していることを、例に知らないキーを足して確かめる。
*/
it('リクエストのスキーマは知らないキーを断り、表現のスキーマは知らないキーを通す', () => {
const validator = schemaValidator(spec);
const request = JSON.parse(read('examples/orders/place-order-request.json')) as { lines: Record<string, unknown>[] };
const order = JSON.parse(read('examples/orders/order.json')) as { lines: Record<string, unknown>[] };
const withTopKey = <T extends object>(value: T) => ({ ...value, unknownKey: 1 });
const withLineKey = <T extends { lines: Record<string, unknown>[] }>(value: T) => ({
...value,
lines: [{ ...value.lines[0], unknownKey: 1 }, ...value.lines.slice(1)],
});
expect(validator('PlaceOrderRequest')(request), '知らないキーの無いリクエスト').toBe(true);
expect(validator('PlaceOrderRequest')(withTopKey(request)), '最上位に知らないキーのあるリクエスト').toBe(false);
expect(validator('PlaceOrderRequest')(withLineKey(request)), '注文明細に知らないキーのあるリクエスト').toBe(false);
expect(validator('Order')(withTopKey(order)), '最上位に知らないキーのある注文の表現').toBe(true);
expect(validator('Order')(withLineKey(order)), '注文明細に知らないキーのある注文の表現').toBe(true);
});

it('Location とパスの変数の例が、注文の例の注文 ID を指す', () => {
const order = JSON.parse(read('examples/orders/order.json')) as { orderId: string };
const paths = isRecord(spec) && isRecord(spec.paths) ? spec.paths : {};
const post = isRecord(paths['/orders']) ? paths['/orders'].post : undefined;
const created = isRecord(post) && isRecord(post.responses) ? post.responses['201'] : undefined;
const location = isRecord(created) && isRecord(created.headers) ? created.headers.Location : undefined;
expect(isRecord(location) ? location.example : undefined).toBe(`/orders/${order.orderId}`);
const item = paths['/orders/{orderId}'];
const parameters = isRecord(item) && Array.isArray(item.parameters) ? item.parameters.filter(isRecord) : [];
expect(parameters.find((parameter) => parameter.name === 'orderId')?.example).toBe(order.orderId);
});

この章のサーバーのコード​

Swagger UI を配るサーバーのコードです。swagger-ui-dist の index.js は、読み込むとブラウザ向けのコードまで読み込むので、import せずに、package.json の場所から配るファイルのディレクトリを求めています。

/*
* 注文 API の仕様 (openapi/openapi.yaml) を、ブラウザの Swagger UI で読むための配信のサーバー。
* 画面のファイルは npm の swagger-ui-dist のものを配り、読む仕様を決める初期化の script だけをここで作る。
* 仕様のファイルはリクエストのたびに読み直すので、仕様を直したらブラウザで読み込み直せば反映される。
*/
import { readFileSync } from 'node:fs';
import { createServer } from 'node:http';
import type { ServerResponse } from 'node:http';
import { createRequire } from 'node:module';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

const port = 3903;
const spec = fileURLToPath(new URL('../../openapi/openapi.yaml', import.meta.url));

/**
* swagger-ui-dist の index.js は、読み込むとブラウザ向けの bundle まで読み込むので import しない。
* package.json の場所から、配るファイルのあるディレクトリだけを求める。
*/
const dist = dirname(createRequire(import.meta.url).resolve('swagger-ui-dist/package.json'));

/** swagger-ui-dist の index.html が読み込むファイルと、その Content-Type。ここに無いパスは 404 にする。 */
const assets: Record<string, string> = {
'/index.html': 'text/html; charset=utf-8',
'/swagger-ui.css': 'text/css; charset=utf-8',
'/index.css': 'text/css; charset=utf-8',
'/swagger-ui-bundle.js': 'text/javascript; charset=utf-8',
'/swagger-ui-standalone-preset.js': 'text/javascript; charset=utf-8',
'/favicon-32x32.png': 'image/png',
'/favicon-16x16.png': 'image/png',
};

/**
* swagger-ui-dist の swagger-initializer.js の代わりに配る、初期化の script。
* 読む仕様をこのサーバーの /openapi.yaml にする。リクエストを送る先がまだ無いので、Try it out は出さない。
*/
const initializer = `window.onload = () => {
window.ui = SwaggerUIBundle({
url: '/openapi.yaml',
dom_id: '#swagger-ui',
supportedSubmitMethods: [],
});
};
`;

function send(res: ServerResponse, status: number, contentType: string, body: string | Buffer): void {
res.writeHead(status, { 'Content-Type': contentType, 'Content-Length': Buffer.byteLength(body) });
res.end(body);
}

/**
* ファイルを読んで返す。読めなければ 500 と理由を返す。仕様のファイルは、tag を切り替えたときや名前を変えたときに無くなりうる。
* readFileSync の例外を捕まえないと、この関数の外で処理されないまま、サーバーのプロセスが止まる。
*/
function sendFile(res: ServerResponse, file: string, contentType: string): void {
let body: Buffer;
try {
body = readFileSync(file);
} catch (error) {
const code = (error as NodeJS.ErrnoException).code ?? String(error);
send(res, 500, 'text/plain; charset=utf-8', `配るファイルを読めません (${code})\n`);
return;
}
send(res, 200, contentType, body);
}

createServer((req, res) => {
// http.Server が渡すリクエストには、url が必ずある (型が省略可なのは、クライアントが受ける応答と型を共用するため)。
const target = req.url!;
/*
* リクエストの対象は、/ で始まるパス (origin-form) のほかに、http://… の絶対形式 (absolute-form) でも届き、
* サーバーは絶対形式も受け付ける (RFC 9112 の 3.2.2)。/ で始まる対象を基準の URL に対して解決すると、// で始まるパスを
* 別のホストと読むので、パスには localhost を前に付ける。
* *:99999 のように URL として読めないものも届く。new URL は読めないと例外を投げ、この関数の外で
* 処理されないまま、サーバーのプロセスが止まるので、読めなければ null を返す URL.parse を使う。
*/
const url = target.startsWith('/') ? URL.parse(`http://localhost${target}`) : URL.parse(target);
if (url === null) return send(res, 400, 'text/plain; charset=utf-8', 'リクエストの対象を URL として読めません\n');
const path = url.pathname;
if (req.method !== 'GET' && req.method !== 'HEAD') {
res.writeHead(405, { Allow: 'GET, HEAD' });
res.end();
return;
}
if (path === '/openapi.yaml') return sendFile(res, spec, 'application/yaml');
if (path === '/swagger-initializer.js') return send(res, 200, 'text/javascript; charset=utf-8', initializer);
const name = path === '/' ? '/index.html' : path;
const contentType = assets[name];
if (contentType === undefined) return send(res, 404, 'text/plain; charset=utf-8', `${path} は見つかりません\n`);
sendFile(res, join(dist, name), contentType);
}).listen(port, () => {
console.log(`Swagger UI を http://localhost:${port} で起動しました`);
});