Skip to main content

モック: Prism で動かして curl と Bruno で呼ぶ

仕様の lintの章では、仕様を Redocly CLI で検査し、ファイルに分けて束ねました。lint が見るのは仕様の書き方です。仕様に沿ってリクエストを送ったときに、アプリを作る人が困らない応答が返るかは、実際に送ってみるまで分かりません。

この章では、束ねた仕様から Prism でモックを動かし、curl と Bruno で呼びます。要件の整理の章の受け入れ条件のうち、モックで確かめられるものを Bruno のリクエストにし、確かめられないものは理由とともに表にします。Swagger UI の Try it out からもモックを呼べるようにします。この章の終わりのリポジトリは、tag rest-13-r2 です。

モックで確かめる理由​

モックは、仕様から決まった応答を返す仮のサーバーです (はじめにの章の 1 周の表)。この章では、モックを 3 つの目的で使います。

1 つ目は、API を呼ぶアプリを作る人が、サーバーの実装を待たずに作り始められることです。仕様の例がそのまま応答に返るので、画面に注文の表現を並べる処理や、誤りの応答を出し分ける処理を先に書けます。

2 つ目は、仕様を、使う側の目で見直すことです。読むだけの見直しでは、リクエストにどのヘッダを付けるとどの応答が返るかまでは確かめません。この章でも、Accept の送り方によって誤りの応答を選べなくなる組み合わせが、モックを呼んで初めて見つかります。

3 つ目は、受け入れ条件の一部を、実装の前に確かめることです。ただし、モックは状態を持たないので、確かめられる受け入れ条件は限られます。どれが確かめられて、どれが確かめられないかを、この章で 1 つずつ決めます。

Prism でモックを起動する​

Prism は、OpenAPI の文書からモックのサーバーを動かす道具です。CLI のコマンドは mock と proxy の 2 つで、この章では mock を使います (Prism CLI)。このガイドでは版を 5.16.0 に固定し、npm の devDependencies に入れました。5.16.0 は Node.js 24.18.0 以上を求め、このガイドの Node.js 26 で動きます。

起動は npm script にしました。

"mock": "npm run bundle && prism mock dist/openapi.yaml --port 3904",
"mock:dynamic": "npm run bundle && prism mock dist/openapi.yaml --port 3905 --dynamic",
"bruno:mock": "cd bruno && bru run --env mock"

npm run mock は、仕様を dist/openapi.yaml に束ねてから、束ねた仕様で Prism を起動します。12 章で決めたとおり、束ねた出力はリポジトリに置かず、読む道具の側が起動の前に束ねます。ポートの既定は 4010 ですが、サンプルリポジトリのほかのサーバー (3901〜3903) に続けて 3904 にしました。mock:dynamic と bruno:mock は、この章の後半で使います。

npm run mock
> rest-api-order@0.0.0 mock
> npm run bundle && prism mock dist/openapi.yaml --port 3904


> rest-api-order@0.0.0 bundle
> redocly bundle openapi/openapi.yaml --output dist/openapi.yaml

bundling openapi/openapi.yaml...
📦 Created a bundle for openapi/openapi.yaml at dist/openapi.yaml 13ms.
[2:30:19 AM] › [CLI] … awaiting Starting Prism…
[2:30:19 AM] › [CLI] ℹ info POST http://127.0.0.1:3904/orders
[2:30:19 AM] › [CLI] ℹ info GET http://127.0.0.1:3904/orders/01a194b4-978e-7c3a-9f21-6d4b8e2a1c05
[2:30:19 AM] › [CLI] ▶ start Prism is listening on http://127.0.0.1:3904

Prism は、仕様から見つけた操作を 1 行ずつ出し、待ち受けを始めます。取得の URL の注文 ID は、パスの変数の例 (example) です。待ち受けるホストの既定は 127.0.0.1 で (prism mock --help の --host)、この章の curl もこのアドレスを使います。この後の例は、モックを起動した端末とは別の端末で打ってください。

例を返す形で呼ぶ​

注文を取得します。

curl -s -i http://127.0.0.1:3904/orders/01a194b4-978e-7c3a-9f21-6d4b8e2a1c05
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: *
Content-type: application/json
Content-Length: 376
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"orderId":"01a194b4-978e-7c3a-9f21-6d4b8e2a1c05","status":"PENDING","placedAt":"2026-11-01T01:23:45.678Z","contactEmail":"taro.test@example.com","lines":[{"productId":"01a0f4c2-c400-7a11-8b52-3c9d0e1f2a34","quantity":2,"unitPrice":1080,"taxRate":8},{"productId":"01a0f4c2-c7e8-7b22-a963-4dae1f203b45","quantity":1,"unitPrice":1650,"taxRate":10}],"total":3810,"taxAmount":310}

本文は、OpenAPIの章で仕様に入れた例 order です。Access-Control- で始まるヘッダは、Prism がどの応答にも付ける CORS のヘッダで、後の Swagger UI の Try it out の節で使います。

注文するも、仕様の例を返します。

curl -s -i http://127.0.0.1:3904/orders \
-H 'Content-Type: application/json' \
-d '{"contactEmail": "taro.test@example.com", "lines": [{"productId": "01a0f4c2-c400-7a11-8b52-3c9d0e1f2a34", "quantity": 2}, {"productId": "01a0f4c2-c7e8-7b22-a963-4dae1f203b45", "quantity": 1}]}'
HTTP/1.1 201 Created
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: *
Location: /orders/01a194b4-978e-7c3a-9f21-6d4b8e2a1c05
Content-type: application/json
Content-Length: 376
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"orderId":"01a194b4-978e-7c3a-9f21-6d4b8e2a1c05","status":"PENDING","placedAt":"2026-11-01T01:23:45.678Z","contactEmail":"taro.test@example.com","lines":[{"productId":"01a0f4c2-c400-7a11-8b52-3c9d0e1f2a34","quantity":2,"unitPrice":1080,"taxRate":8},{"productId":"01a0f4c2-c7e8-7b22-a963-4dae1f203b45","quantity":1,"unitPrice":1650,"taxRate":10}],"total":3810,"taxAmount":310}

201 と Location が返りました。Location の値は、仕様の 201 の応答のヘッダの例です。

Prism が応答を選ぶ手順は、文書の判定の図にあります (Prism Decision Engine)。リクエストが仕様に合い、ステータスコードの指定が無ければ、仕様の 2xx の応答のうち最も小さいもの (注文するなら 201) を選び、その例を返します。リクエストの中身は、応答の値に使いません。別の購入者が別の商品を頼んでも、同じ例が返ります。

curl -s http://127.0.0.1:3904/orders \
-H 'Content-Type: application/json' \
-d '{"contactEmail": "hanako.test@example.com", "lines": [{"productId": "01a0f4c2-c7e8-7b22-a963-4dae1f203b45", "quantity": 3}]}'
{"orderId":"01a194b4-978e-7c3a-9f21-6d4b8e2a1c05","status":"PENDING","placedAt":"2026-11-01T01:23:45.678Z","contactEmail":"taro.test@example.com","lines":[{"productId":"01a0f4c2-c400-7a11-8b52-3c9d0e1f2a34","quantity":2,"unitPrice":1080,"taxRate":8},{"productId":"01a0f4c2-c7e8-7b22-a963-4dae1f203b45","quantity":1,"unitPrice":1650,"taxRate":10}],"total":3810,"taxAmount":310}

モックは注文を作らず、覚えてもいません。Prism の README の今後の予定にも、データを持ってサンドボックスのように振る舞う機能は、まだ済んでいない項目として載っています (Roadmap)。そのため、どの注文 ID で取得しても、注文の例が返ります。

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3904/orders/no-such-order
200

エラーの設計の章では、注文 ID の形でない値も、その注文が無いものとして 404 にすると決めました。モックはその判断をしません。仕様のパスの変数には形を書いていないので、どの値もリクエストとしては正しく、注文の例を返します。

Prefer ヘッダで応答を選ぶ​

例を返すだけでは、誤りの応答を受け取る処理を作れません。Prism は、リクエストの Prefer ヘッダで、返す応答を選ばせます (Modifying Responses)。code でステータスコードを、example で名前付きの例を選びます。ヘッダを付けにくい道具のために、同じ指定を __code のようなクエリ文字列でも書けます。

curl -s -i http://127.0.0.1:3904/orders/01a194b4-978e-7c3a-9f21-6d4b8e2a1c05 \
-H 'Accept: application/json, application/problem+json' \
-H 'Prefer: code=404'
HTTP/1.1 404 Not Found
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: *
Content-type: application/problem+json
Content-Length: 75
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"type":"/problems/order-not-found","title":"Order not found","status":404}

Accept は、仕様の説明 (info.description) が勧める application/json, application/problem+json にしました。理由は、この節の最後に見ます。

注文するの 400 には、3 つの名前付きの例 (invalid-request・unknown-product・insufficient-inventory) があります。code と example を組み合わせると、そのうちの 1 つを選べます。

curl -s http://127.0.0.1:3904/orders \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, application/problem+json' \
-H 'Prefer: code=400, example=insufficient-inventory' \
-d '{"contactEmail": "taro.test@example.com", "lines": [{"productId": "01a0f4c2-c7e8-7b22-a963-4dae1f203b45", "quantity": 4}]}'
{"type":"/problems/insufficient-inventory","title":"Insufficient inventory","status":400,"detail":"1 product in the order does not have enough inventory.","productIds":["01a0f4c2-c7e8-7b22-a963-4dae1f203b45"]}

example に書く名前は、仕様の examples のキーです。11 章では、このキーを components/examples の名前と同じにしておいたので、仕様のどちらを見ても同じ名前で選べます。

code を付けずに example だけを書くと、注文するでは Prism 自身の 404 が返りました。本文は、application/json の中に insufficient-inventory の例が無いと書いています。Prism の文書の注記は、code を付けないと、example の名前を 200 の応答だけから探すと書いています (Dynamic Response)。注文するには 200 が無く、成功の応答は 201 です。誤りの応答の例を選ぶときは、code と組にします。

curl -s http://127.0.0.1:3904/orders \
-H 'Content-Type: application/json' \
-H 'Prefer: example=insufficient-inventory' \
-d '{"contactEmail": "taro.test@example.com", "lines": [{"productId": "01a0f4c2-c7e8-7b22-a963-4dae1f203b45", "quantity": 4}]}'
{"type":"https://stoplight.io/prism/errors#NOT_FOUND","title":"The server cannot find the requested content","status":404,"detail":"Response for contentType: application/json and exampleKey: insufficient-inventory does not exist."}

最後に、Accept を application/json だけにして、404 を頼みます。

curl -s -o /dev/null -w '%{http_code} %{content_type}\n' http://127.0.0.1:3904/orders/01a194b4-978e-7c3a-9f21-6d4b8e2a1c05 \
-H 'Accept: application/json' \
-H 'Prefer: code=404'
200 application/json

404 を頼んだのに、200 と注文の表現が返りました。仕様の 404 の本文は application/problem+json だけで、Accept: application/json はそれを受け入れません。Prism の判定の図では、指定したステータスコードの応答で Accept に合う形が見つからないと、最も小さい 2xx の応答に戻ります。注文するに Prefer: code=400 を付けたときも、Accept: application/json だけなら 201 が返りました。code に example (insufficient-inventory) を添えると、Prism の 500 (…#UNKNOWN) になりました。500 の本文は、既定の応答を試したがその例が見つからなかったと書いています。

Prefer で誤りの応答を選ぶときは、Accept に application/problem+json も入れます。仕様の説明は、もともとこの Accept を勧めています。表現の設計の章と 10 章で、誤りの応答を Accept に関わらず問題の詳細で返すと決めたので、クライアントが問題の詳細を受け入れると書いておくのが素直だからです。Prefer を付けないリクエストが検証に落ちたとき (次の節) は、Accept: application/json だけでも、400 が問題の詳細で返りました。

Prism のリクエストの検証​

Prism は、リクエストの本文・ヘッダ・クエリ・パスの変数を、仕様のスキーマで確かめます (Request Validation)。連絡先メールアドレスの無い注文を送ります。

curl -s -i http://127.0.0.1:3904/orders \
-H 'Content-Type: application/json' \
-d '{"lines": [{"productId": "01a0f4c2-c400-7a11-8b52-3c9d0e1f2a34", "quantity": 1}]}'
HTTP/1.1 400 Bad Request
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: *
sl-violations: [{"location":["request","body"],"severity":"Error","code":"required","message":"Request body must have required property 'contactEmail'"}]
Content-type: application/problem+json
Content-Length: 204
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"type":"/problems/invalid-request","title":"Invalid request","status":400,"detail":"The request body has an error.","errors":[{"pointer":"/lines/0/quantity","detail":"Must be an integer of 1 or more."}]}

400 で断られました。違反の中身 (必須の contactEmail が無い) は、sl-violations ヘッダに出ています。本文は、仕様の 400 の最初の例 invalid-request そのままで、注文明細の数量の誤りを指しています。送った誤りとは違います。

Prism は、検証に落ちたリクエストに、操作の 422 の応答を探し、無ければ 400 を探して返します (Parameter Validation)。返す本文は、判定の図のとおり、名前で選んだ例か、選ばなければ最初の例です。モックは誤りの中身から本文を作らないので、どの誤りを送っても、本文は同じです。誤りの中身を知るには sl-violations を読みます。

知らないキーを持つ注文も断ります。11 章で、リクエストのスキーマを additionalProperties: false で閉じたからです。

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3904/orders \
-H 'Content-Type: application/json' \
-d '{"contactEmail": "taro.test@example.com", "coupon": "WINTER", "lines": [{"productId": "01a0f4c2-c400-7a11-8b52-3c9d0e1f2a34", "quantity": 1}]}'
400

同じ商品の注文明細を 2 つ並べた注文は、受け付けます。

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3904/orders \
-H 'Content-Type: application/json' \
-d '{"contactEmail": "taro.test@example.com", "lines": [{"productId": "01a0f4c2-c400-7a11-8b52-3c9d0e1f2a34", "quantity": 1}, {"productId": "01a0f4c2-c400-7a11-8b52-3c9d0e1f2a34", "quantity": 1}]}'
201

09 章で決めた「同じ商品の注文明細は 1 つまで」は、JSON Schema の uniqueItems では書けません。uniqueItems が比べるのは注文明細の全体で、商品 ID が同じでも数量が違えば別の要素になるからです。仕様のスキーマに書けない決まりは、モックには見えません。

検証と Prefer を組み合わせると、もう 1 つ気をつける点があります。メールアドレスの無い注文に、在庫不足の例を頼みます。

curl -s -i http://127.0.0.1:3904/orders \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, application/problem+json' \
-H 'Prefer: code=400, example=insufficient-inventory' \
-d '{"lines": [{"productId": "01a0f4c2-c7e8-7b22-a963-4dae1f203b45", "quantity": 4}]}'
HTTP/1.1 400 Bad Request
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: *
sl-violations: [{"location":["request","body"],"severity":"Error","code":"required","message":"Request body must have required property 'contactEmail'"}]
Content-type: application/problem+json
Content-Length: 209
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"type":"/problems/insufficient-inventory","title":"Insufficient inventory","status":400,"detail":"1 product in the order does not have enough inventory.","productIds":["01a0f4c2-c7e8-7b22-a963-4dae1f203b45"]}

違反は sl-violations に出ていますが、ステータスコードも本文も、頼んだ在庫不足の例です。本文とステータスコードだけを見る確かめは、リクエストが仕様に反していても通ります。リクエストが仕様に合うかをモックで確かめるときは、Prefer を付けません。

誤りの応答と、エラーの設計の章の決まりの違い​

操作の外の失敗には、Prism は自分の型の問題の詳細を返します (Errors)。仕様に無いパスを呼びます。

curl -s http://127.0.0.1:3904/products
{"type":"https://stoplight.io/prism/errors#NO_PATH_MATCHED_ERROR","title":"Route not resolved, no path matched","status":404,"detail":"The route /products hasn't been found in the specification file"}

注文を DELETE で呼びます。

curl -s -i -X DELETE http://127.0.0.1:3904/orders/01a194b4-978e-7c3a-9f21-6d4b8e2a1c05
HTTP/1.1 405 Method Not Allowed
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: *
content-type: application/problem+json
Content-Length: 260
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"type":"https://stoplight.io/prism/errors#NO_METHOD_MATCHED_ERROR","title":"Route resolved, but no method matched","status":405,"detail":"The route /orders/01a194b4-978e-7c3a-9f21-6d4b8e2a1c05 has been matched, but it does not have \"delete\" method defined"}

405 に Allow ヘッダがありません。Accept に HTML だけを書くと 406 です。

curl -s http://127.0.0.1:3904/orders/01a194b4-978e-7c3a-9f21-6d4b8e2a1c05 -H 'Accept: text/html'
{"type":"https://stoplight.io/prism/errors#NOT_ACCEPTABLE","title":"The server cannot produce a representation for your accept header","status":406,"detail":"Unable to find content for text/html"}

仕様には 406 の応答と例 (about:blank) がありますが、Prism はそれを使わず、自分の 406 を作りました。Prism は Prefer の無いリクエストに、最も小さい 2xx の応答 (取得なら 200) を選び、その本文の形 (application/json) が Accept に合わないと、自分の 406 を返します。Accept: application/problem+json だけを送っても、同じく Prism の 406 でした。本文を JSON でなく送ると 415 です。

curl -s -i http://127.0.0.1:3904/orders -H 'Content-Type: text/plain' -d 'apple 2'
HTTP/1.1 415 Unsupported Media Type
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: *
sl-violations: [{"location":["request"],"severity":"Error","code":415,"message":"Supported content types: application/json"}]
Accept: application/json
Content-type: application/problem+json
Content-Length: 68
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"type":"about:blank","title":"Unsupported Media Type","status":415}

415 は、仕様の 415 の例と Accept ヘッダの例を返しました。判定の図は、415 の誤りで仕様に 415 の応答があれば、それを返すとしています。

10 章の docs/api-design/problems.md の決まりと並べると、次のようになります。

失敗10 章の決まりPrism 5.16.0 のモック
本文の形か値の誤り400 /problems/invalid-request。最初に見つけた誤りを 1 つだけ errors に入れる400。本文は仕様の最初の例のまま。誤りの中身は sl-violations ヘッダ
在庫不足・登録されていない商品400 (insufficient-inventory・unknown-product)返さない。形の正しい注文は 201 (Prefer で頼めば例を返す)
同じ商品の注文明細の重なり400 /problems/invalid-request201
注文が無い404 /problems/order-not-found返さない。どの注文 ID も 200 (Prefer で頼めば例を返す)
一覧に無いパス404 about:blank404 …#NO_PATH_MATCHED_ERROR
受け付けないメソッド405 about:blank と Allow405 …#NO_METHOD_MATCHED_ERROR。Allow は無い
Accept が application/json を受け入れない406 about:blank406 …#NOT_ACCEPTABLE
本文が application/json でない415 about:blank と Accept: application/json仕様の 415 の例と Accept

アプリを作る人がモックで確かめられるのは、仕様に書いた応答の形 (ステータスコード・本文のメディアタイプ・例) です。操作の外の失敗の本文や、誤りの中身はサーバーと違うので、モックの値に合わせて画面の処理を書かないでください。問題の型は type で見分けると 10 章で決めたので、知らない type を受け取っても止まらない作りにしておけば、モックとサーバーの違いはそこで吸収できます。

type の値は、相対 URI (/problems/invalid-request) のまま本文に入ります。10 章で決めたとおり、受け手が識別子として使うのは、相対 URI を応答の文書の基準の URI に対して解決した URI です。モック (http://127.0.0.1:3904) と第 2 部で作るサーバーで、基準の URI のスキームか authority (ホストとポートの部分) が違えば、解決した URI も違います。この章の Bruno の assert は、本文の値を相対 URI の文字列のまま比べます。

値を作る形のモック​

ここまでのモックは、仕様の例を返す形 (静的な生成) でした。Prism には、仕様のスキーマから応答の値を毎回作る形 (動的な生成) もあります (Static or Dynamic Generation)。同じ値だけで試し続けると、長い名前や 0 のような値を受け取ったときの不具合に気づけないので、そのための形です。npm run mock:dynamic は、--dynamic を付けて 3905 で起動します。

npm run mock:dynamic

mock:dynamic も起動の前に束ね直すので、先に npm run mock を起動していれば、そちらの Prism も束ね直した文書を読み直します (中身は同じです。読み直しは見直しの節で扱います)。静的な形のモックでも、リクエストごとに Prefer: dynamic=true を付ければ、値を作らせられます。注文が見つからない応答を、値を作る形で取ります。

curl -s -i -w '\n%{http_code}\n' http://127.0.0.1:3905/orders/01a194b4-978e-7c3a-9f21-6d4b8e2a1c05 \
-H 'Accept: application/json, application/problem+json' \
-H 'Prefer: code=404'
HTTP/1.1 404 Not Found
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: *
Content-type: application/problem+json
Content-Length: 94
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"detail":"quis id","status":404,"title":"Order not found","type":"/problems/order-not-found"}
404

type・title・status は、仕様のスキーマが値を 1 つに決めているので毎回同じで、detail は呼ぶたびに違う文字列になります。値が変わるので、この結果は記事の値と比べられません。サンプルリポジトリのテストは、値を作るモックへの例について、最後の行のステータスコードを期待値と比べ、本文を仕様のスキーマで確かめます。ステータスコードとメソッドとパスで仕様の応答を探し、見つからなければ、それも失敗にします (章末のこの章のテストのコード)。

この確かめが見るのは、応答の形が仕様に合うことだけです。値が毎回変わることは見ていないので、例を返す形のモックの応答でも通ります。値を作るモックへ送ったことは、別の 2 つの確かめで守っています。1 つは、servers.json でスキーマの確かめを付けたサーバーと、起動のコマンドが prism mock に --dynamic を付けるサーバーが、同じであること。もう 1 つは、そのサーバーへ送って本文をスキーマで確かめた例が、1 つ以上あることです。例の送り先を例を返すモックに書き誤ると、2 つ目で落ちます。

値を作る形の例に注文の表現でなく誤りの応答を選んだのは、Prism 5.16.0 が作る注文の表現が、仕様のスキーマに合わないからです。理由は実務で効く注意点に書きました。prism mock --help には、作る値を種 (seed) で固定する --seed もあります。

Bruno でリクエストを残す​

curl の例は記事には向きますが、受け入れ条件を確かめるリクエストを、毎回手で打つのは手間です。この章では、リクエストを Bruno のコレクションにして、リポジトリに置きます。Bruno は、コレクションをプレーンテキストのファイルとしてフォルダに保存する API のクライアントで、使うのにアカウントは要りません (Why Bruno)。Bruno の宣言は、コレクションを API のソースコードと同じリポジトリに置き、API の使い方の生きた例にするよう勧めています (Manifesto)。保存の形は、新しいコレクションでは OpenCollection YAML が勧められています (Bru Lang Overview)。

CLI (@usebruno/cli) は、版を 4.3.0 に固定して devDependencies に入れました。

仕様からコレクションを読み込む​

bru import openapi は、OpenAPI の仕様を Bruno のコレクションに変えます (Import)。

npx bru import openapi --source dist/openapi.yaml --output dist/bruno-import --collection-name 注文API

できたファイルは次のとおりです。

dist/bruno-import/environments/仕様を配っているサーバーと同じオリジン.yml
dist/bruno-import/opencollection.yml
dist/bruno-import/orders/folder.yml
dist/bruno-import/orders/注文する.yml
dist/bruno-import/orders/注文を確かめる.yml

リクエストは仕様の tags (orders) ごとのフォルダに入り、ファイル名は操作の summary から、環境の名前は servers の description から作られます。環境の baseUrl は空です。Bruno の読み込みは servers の url の末尾の / を削って baseUrl にするので (openapi-to-bruno.js)、url が / だけの仕様では空になります。応答の例は、各リクエストの見本 (examples) になり、assert は作られません。

読み込みは、仕様にあるリクエストを一度に並べる入口として使えます。この章では、リポジトリに置くコレクションを手で書きました。日本語のファイル名 (summary と description から作る) をリポジトリとコマンドで扱いにくいことと、受け入れ条件ごとのリクエストと assert は、どのみち手で書くことになるからです。

手で書いたコレクション​

find bruno -name '*.yml' | LC_ALL=C sort
bruno/environments/mock.yml
bruno/get-order/accepted-order.yml
bruno/get-order/folder.yml
bruno/opencollection.yml
bruno/place-order/accepted.yml
bruno/place-order/folder.yml
bruno/place-order/invalid-contact-email.yml
bruno/place-order/no-contact-email.yml
bruno/place-order/no-lines.yml
bruno/place-order/quantity-zero.yml

フォルダは 04 章のストーリー (place-order/ が注文する、get-order/ が注文を確かめる) で、folder.yml にストーリーの名前を書きました。

コレクションの root の opencollection.yml には、コレクションの名前と、どのリクエストにも付けるヘッダを書きました。

opencollection: 1.0.0

info:
name: 注文 API

docs:
content: |
docs/requirements/stories.md の受け入れ条件のうち、モックで確かめられるものを、1 つずつリクエストにしたもの。
モックで確かめられない受け入れ条件と、その理由は docs/getting-started.md の表にある。
type: text/markdown

# どのリクエストにも、仕様 (info.description) が勧める Accept を付ける。
# 誤りの応答は問題の詳細 (application/problem+json) で返るので、クライアントとしてそれを受け入れると書いておく。
request:
headers:
- name: Accept
value: application/json, application/problem+json

request は、コレクションやフォルダのリクエストの既定の設定です (OpenCollection のスキーマ の RequestDefaults)。Accept をここに置くと、リクエストのファイルごとに書かずに済みます。

環境は environments/ に 1 つずつ置きます (Environment Variables)。モックの環境は、送り先の baseUrl だけを持ちます。

name: mock
variables:
- name: baseUrl
value: http://127.0.0.1:3904

リクエストは、受け入れ条件 1 つに 1 ファイルです。在庫のある商品を注文する受け入れ条件は、次のようになります。

info:
name: 在庫のある商品を注文すると、注文が受け付けられる
type: http
seq: 1

http:
method: POST
url: "{{baseUrl}}/orders"
body:
type: json
data: |-
{
"contactEmail": "taro.test@example.com",
"lines": [
{ "productId": "01a0f4c2-c400-7a11-8b52-3c9d0e1f2a34", "quantity": 2 },
{ "productId": "01a0f4c2-c7e8-7b22-a963-4dae1f203b45", "quantity": 1 }
]
}

runtime:
scripts:
- type: after-response
code: |-
bru.setVar("orderId", res.body.orderId);
assertions:
- expression: res.status
operator: eq
value: "201"
- expression: res.headers.location
operator: eq
value: /orders/{{orderId}}
- expression: res.body.status
operator: eq
value: PENDING
- expression: res.body.lines
operator: length
value: "2"
- expression: res.body.lines[0].unitPrice
operator: eq
value: "1080"
- expression: res.body.lines[1].unitPrice
operator: eq
value: "1650"
- expression: res.body.total
operator: eq
value: "3810"
- expression: res.body.taxAmount
operator: eq
value: "310"

info.name は受け入れ条件の見出しと同じ文にし、info.seq でフォルダの中の並びを決めます。runtime.assertions は JavaScript を書かずに並べる assert で、expression に確かめる値、operator に比べ方、value に期待する値を書きます (runtime.assertions)。YAML に書く比べ方の語は eq や length です。アプリのリクエストの Assert のタブでは、eq は equals、neq は notEquals の名前で出て、ほかの語 (length など) はそのまま出ます。

runtime.scripts の after-response は、応答を受け取った後に動く script です。ここでは bru.setVar で、応答の注文 ID を実行中だけの変数に入れました (bru.setVar)。注文を確かめるリクエストは、この変数で取得します。受け入れ条件の Given (「在庫のある商品を注文すると…」の注文が受け付けられている) と同じ流れです。

info:
name: 受け付けた注文を、注文 ID で確かめられる
type: http
seq: 1

http:
method: GET
url: "{{baseUrl}}/orders/{{orderId}}"

runtime:
assertions:
- expression: res.status
operator: eq
value: "200"
- expression: res.body.orderId
operator: eq
value: "{{orderId}}"

この後に、状態・注文日時・注文明細の数・合計・消費税額・連絡先メールアドレスの assert が続きます。注文日時は、値でなく形を matches (正規表現) で比べました。受け入れ条件の Then は注文日時を Given の時刻にしますが、実装したサーバーに同じリクエストを送ると、注文日時は送った時刻になります。モックでも実装でも成り立つ形にとどめ、注文日時が受け付けた時刻になることは、実装のテストで時計を決めて確かめます。

Bruno のアプリでは、bruno/ のフォルダをコレクションとして開き (Open Collection)、右上の環境の欄で mock を選んでから送ります。送った後の応答の欄の Tests のタブに、assert の結果が YAML と同じ eq の形で出ます。画面は Bruno 4.3.0 のアプリのものです。

Bruno のアプリで「在庫のある商品を注文すると、注文が受け付けられる」を送った画面。中央にリクエストの本文、右の Tests のタブに 201 Created と、8 個の assert がどれも通った結果が出ている

bru run で回す​

bru run は、コレクションのリクエストを順に送り、assert の結果を出します。コレクションの root (opencollection.yml のあるフォルダ) で回す決まりで (bru run)、root の外で回すと You can run only at the root of a collection と出て止まります。npm script の bruno:mock は、bruno/ に移ってから回します。npm script の中の cd は、打った人のシェルの場所を変えません。

npm run bruno:mock
> rest-api-order@0.0.0 bruno:mock
> cd bruno && bru run --env mock

place-order/accepted (201 Created) - 3 ms
Assertions
✓ res.status: eq 201
✓ res.headers.location: eq /orders/{{orderId}}
✓ res.body.status: eq PENDING
✓ res.body.lines: length 2
✓ res.body.lines[0].unitPrice: eq 1080
✓ res.body.lines[1].unitPrice: eq 1650
✓ res.body.total: eq 3810
✓ res.body.taxAmount: eq 310
place-order/quantity-zero (400 Bad Request) - 3 ms
Assertions
✓ res.status: eq 400
✓ res.body.type: eq /problems/invalid-request
place-order/no-lines (400 Bad Request) - 3 ms
Assertions
✓ res.status: eq 400
✓ res.body.type: eq /problems/invalid-request
place-order/no-contact-email (400 Bad Request) - 3 ms
Assertions
✓ res.status: eq 400
✓ res.body.type: eq /problems/invalid-request
place-order/invalid-contact-email (400 Bad Request) - 3 ms
Assertions
✓ res.status: eq 400
✓ res.body.type: eq /problems/invalid-request
get-order/accepted-order (200 OK) - 3 ms
Assertions
✓ res.status: eq 200
✓ res.body.orderId: eq {{orderId}}
✓ res.body.status: eq PENDING
✓ res.body.placedAt: matches ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
✓ res.body.lines: length 2
✓ res.body.total: eq 3810
✓ res.body.taxAmount: eq 310
✓ res.body.contactEmail: eq taro.test@example.com

📊 Execution Summary
┌───────────────┬──────────────┐
│ Metric │ Result │
├───────────────┼──────────────┤
│ Status │ ✓ PASS │
├───────────────┼──────────────┤
│ Requests │ 6 (6 Passed) │
├───────────────┼──────────────┤
│ Tests │ 0/0 │
├───────────────┼──────────────┤
│ Assertions │ 24/24 │
├───────────────┼──────────────┤
│ Duration (ms) │ 80 │
└───────────────┴──────────────┘

所要時間 (- 3 ms と Duration) は実行のたびに変わるので、記事とテストでは決まった値に置き換えています。assert か script のテストか、リクエストのどれかが失敗すると、bru run は終了コード 1 で終わります (run.js)。CI に入れれば、受け入れ条件と仕様の例の食い違いで止まります。

アプリでは、コレクションの Runner で同じ 6 つのリクエストを順に回せます。

Bruno のアプリの Runner でコレクションを回した画面。All 6・Passed 6・Failed 0 で、6 つのリクエストごとに assert の結果が並ぶ

同じコレクションを、値を作る形のモックへ向けて回すと、値の assert が外れます。--env-var は環境の変数を 1 つ上書きします (Options)。

npm run bruno:mock -- --env-var baseUrl=http://127.0.0.1:3905
place-order/accepted (201 Created) - 28 ms
Assertions
✓ res.status: eq 201
✕ res.headers.location: eq /orders/{{orderId}}
expected '/orders/01a194b4-978e-7c3a-9f21-6d4b8…' to equal '/orders/sunt quis ad occaecat in'
✕ res.body.status: eq PENDING
expected 'Duis veniam amet aute adipisicing' to equal 'PENDING'
✕ res.body.lines: length 2
expected [ { …(11) }, { …(10) }, …(98) ] to have a length of 2 but got 100

上は出力の最初のリクエストの部分です。ステータスコードの assert は通り、値の assert は外れます。Location は仕様のヘッダの例のままで、本文の注文 ID は作った値なので、2 つが食い違っています。受け入れ条件は具体的な値で書いたので、それを確かめるには例を返す形のモックを使います。

終了コード 1 だけでは、送り先を誤って接続を断られたときと見分けがつきません。サンプルリポジトリのテスト (test/bruno.test.ts) は、どのリクエストも送り先に届き (ECONNREFUSED が無い)、assert の外れ (✕) があることも確かめます。

出力をファイルに書き出して (端末でなく) 回すと、Bruno CLI 4.3.0 は FORCE_COLOR=1 のときだけ色の符号を付けました。NO_COLOR=1 を足しても消えず、CI と GITHUB_ACTIONS の環境変数では付きませんでした。出力をファイルに比べる CI で FORCE_COLOR を設定しているなら、外してから回してください。サンプルリポジトリのテストは、コマンドに FORCE_COLOR を渡しません。

受け入れ条件を Bruno のリクエストにする​

04 章の受け入れ条件は 11 個です。モックで確かめられるかで、3 つに分かれます。

  • 例の値と比べられるもの: 在庫のある商品を注文する・受け付けた注文を確かめる。仕様の例は、09 章でこの 2 つの受け入れ条件の値から作りました。モックの応答と受け入れ条件の値を比べると、例と受け入れ条件の食い違いが分かります
  • 仕様のスキーマで断れるもの: 数量が 1 より小さい・注文明細が無い・連絡先メールアドレスが無い・形が正しくない。モックが 400 で断ることで、仕様がこの誤りを断る形に書けていることが分かります。どの誤りかは分かりません
  • モックで確かめられないもの: 在庫より多い数量・一部の在庫不足・登録されていない商品・同じ商品が 2 つ・無い注文 ID。在庫・商品・注文の有無はモックに無く、重なりは仕様のスキーマに書けません

確かめられる 6 つを Bruno のリクエストにし、確かめられない 5 つは、docs/getting-started.md の表に理由とともに置きました。

| 受け入れ条件 | Bruno のリクエスト | モックで確かめられないこと |
| --- | --- | --- |
| 在庫のある商品を注文すると、注文が受け付けられる | `bruno/place-order/accepted.yml` | 在庫が減ること (API に在庫を読む操作が無く、実装のテストで確かめる) |
| 在庫より多い数量を頼むと、注文は受け付けられない | — | 在庫が足りないこと (モックは在庫を持たず、形の正しい注文を受け付ける)。在庫が変わらないことは実装のテストで確かめる |
| 一部の商品の在庫が足りないと、注文全体が受け付けられない | — | 在庫が足りないこと (同上)。在庫が変わらないことは実装のテストで確かめる |
| 登録されていない商品を頼むと、注文は受け付けられない | — | 商品が登録されていないこと (モックは商品を持たない)。在庫が変わらないことは実装のテストで確かめる |
| 数量が 1 より小さい注文明細があると、注文は受け付けられない | `bruno/place-order/quantity-zero.yml` | どの注文明細の数量が誤りか (モックは誤りの中身によらず、仕様の最初の例を返す) |
| 注文明細が 1 つも無いと、注文は受け付けられない | `bruno/place-order/no-lines.yml` | 誤りが注文明細の無いことだと分かること (同上) |
| 同じ商品の注文明細が 2 つあると、注文は受け付けられない | — | 同じ商品の重なり (仕様のスキーマで書けない決まりなので、モックは注文を受け付ける)。在庫が変わらないことは実装のテストで確かめる |
| 連絡先メールアドレスが無いと、注文は受け付けられない | `bruno/place-order/no-contact-email.yml` | 誤りが連絡先メールアドレスの無いことだと分かること (同上) |
| 連絡先メールアドレスの形が正しくないと、注文は受け付けられない | `bruno/place-order/invalid-contact-email.yml` | 誤りが連絡先メールアドレスの形だと分かること (同上) |
| 受け付けた注文を、注文 ID で確かめられる | `bruno/get-order/accepted-order.yml` | 確かめた注文が、受け付けた注文であること (モックはどの注文 ID にも同じ例を返す)。注文日時が受け付けた時刻であること (リクエストは注文日時の形だけを確かめる) |
| 無い注文 ID では、注文が見つからない | — | 注文が無いこと (モックはどの注文 ID にも注文の例を返す) |

確かめられない受け入れ条件も、リクエストを書いて回す対象から外すだけにする手はあります (Bruno の --exclude-tags など)。この章では採りませんでした。モックで一度も回らないリクエストは、書き誤っていても気づけないファイルとして残るからです。それらのリクエストは、サーバーを実装して回せるようになってから足します。

表とコレクションと受け入れ条件の文書は、どれかを直して残りを直し忘れると食い違います。test/bruno.test.ts は、次の 4 つを確かめます (章末)。

  • 表の行が、受け入れ条件と同じものを同じ順に持つ
  • 表が指すリクエストが、その受け入れ条件の名前を持ち、そのストーリーのフォルダにある
  • どのリクエストも、表から指されている
  • どのリクエストも、ステータスコードの assert を持つ

assert には、サーバーを実装した後も同じ値になるものだけを書きました。ステータスコード・type・受け入れ条件の値です。誤りの応答の errors の中身は、モックでは仕様の例のままなので書いていません。

受け入れ条件の直し​

受け入れ条件をリクエストにする途中で、4 つの受け入れ条件の When に、連絡先メールアドレスが無いことに気づきました。在庫より多い数量を頼む受け入れ条件は、04 章では「保存容器を 4 個注文する」とだけ書いていました。そのままリクエストにすると、メールアドレスの無い注文になり、在庫を確かめる前に、本文の形の誤り (invalid-request) で断られます。確かめたい誤りでない誤りで受け入れ条件が通ってしまうので、4 つの When にメールアドレスを足しました。

### 受け入れ条件: 在庫より多い数量を頼むと、注文は受け付けられない

- **Given** 受け入れ条件の前提の商品と在庫がある
- **When** 購入者が、保存容器を 4 個、連絡先メールアドレス `taro.test@example.com` で注文する
- **Then** 注文は作られない
- **And** 在庫が足りない商品が保存容器だと分かる
- **And** 保存容器の在庫は 3 のまま

見出しの文は変えていないので、受け入れ条件のテストの名前 (04 章) は直していません。数量が 1 より小さい・注文明細が無いの 2 つも、メールアドレスが無いと、確かめたい誤りより先にメールアドレスの誤りがあることになります。誤りを 1 つだけ含むリクエストを書けるよう、受け入れ条件の側を直しました。

始めるための手順を文書にする​

アプリを作る人は、この章のように記事を読んでからリポジトリを使うとは限りません。docs/getting-started.md に、リポジトリを取得してモックを起動し、curl・Bruno・Swagger UI で呼ぶまでの手順を置きました。中身は、モックの起動・例の商品 ID で注文して返った注文 ID で確かめる curl・Prefer で応答を選ぶ方法と Accept の注意・Bruno と Swagger UI での呼び方・上の受け入れ条件の表・例の商品 ID の表です。11 章で、利用者が読む文書のうち手順の文書 (注文を 1 件作って確かめるまで) として予定したものです。

例の商品 ID の表は、受け入れ条件の前提の商品 (りんご・保存容器) と、仕様の例が使う商品 ID の対応です。これまで、この対応は記事の地の文にしかありませんでした。1 周目の購入者は商品 ID を API の外から知っているという仮定も、docs/api-design/endpoints.md に足しました。前提の商品をこの商品 ID で登録すれば、仕様の例と Bruno のリクエストを、実装したサーバーにもそのまま使えます。test/bruno.test.ts は、表の商品 ID が examples/ の JSON にあることと、表の商品が受け入れ条件の前提の価格と税率で、注文の例の同じ商品 ID の注文明細にあることも確かめます。

Swagger UI の Try it out でモックを呼ぶ​

11 章では、送る先が無いので、Swagger UI の Try it out を出しませんでした。モックができたので、Try it out からモックへ送れるようにします。

Try it out の送り先は、仕様の servers から選びます。注文の API の仕様の servers は / です。相対の URL は、仕様の文書を配っている場所を基準に解決されます (Server Object)。Swagger UI の配信のサーバー (http://localhost:3903) が仕様を配るので、/ は配信のサーバー自身を指し、そこには注文の API がありません。

モックへ送る形は 3 つ考えられます。

形採否理由
仕様の servers にモックの URL を足す採らないservers は API を置く場所を表す。手元のモックの URL は、仕様を読む人の誰にでも当てはまる場所ではない
配信のサーバーが、注文の API へのリクエストをモックへ中継する採らない同じオリジンに見えるので CORS の設定が要らなくなり、別のオリジンの API を画面から呼ぶときの設定を確かめられない
配信のサーバーが、配る仕様の servers の先頭にモックを足す採る仕様のファイルは変えない。Try it out は別のオリジンのモックへ送るので、CORS の設定をモックの側で確かめられる

配信のサーバーは、dist/openapi.yaml を読み、servers の先頭にモック (http://127.0.0.1:3904、説明は「モック (npm run mock)」) を足してから配ります。Prism は 127.0.0.1 で待ち受けるので、localhost (::1 に解決されうる) でなく 127.0.0.1 と書きました。コードは章末のこの章のサーバーのコードにあります。test/swagger-ui.test.ts は、配信のサーバーを動かして /openapi.yaml を取り、servers の先頭がこのモックで、そのポートが記事の例のモックと同じであることを確かめます。配信のサーバーが決まったパスの dist/openapi.yaml を読むので、このテストはテストの中で dist/openapi.yaml に束ねます (12 章で決めたテストの仕様の読み込みは、一時のファイルに束ねて、dist/ を読みません)。読めない中身を書いて 500 を確かめた後は、束ね直して元に戻します。

初期化の script からは、11 章で Try it out を止めるために書いた supportedSubmitMethods: [] を外しました。12 章の束ねるの節の表では、配信のサーバーは dist/openapi.yaml を配ると書きました。この章からは、dist/openapi.yaml を読んで servers を足したものを配ります。仕様の中身は同じで、servers の並びだけが違います。

npm run docs:swagger

モックを起動したまま、別の端末で上のコマンドを打ち、http://localhost:3903 を開きます。Servers に「モック (npm run mock)」が選ばれているので、Try it out の Execute でモックへリクエストが届きます。画面は Swagger UI 5.34.1 のものです。

Swagger UI の最初の画面。info の説明の下の Servers の欄で、http://127.0.0.1:3904 - モック (npm run mock) が選ばれている

注文を確かめる操作 (GET /orders/{orderId}) を開いて Try it out を押すと、orderId の欄に仕様の例の注文 ID が入ります。Execute を押すと、送ったリクエストを表す curl のコマンドと Request URL、モックの応答 (Server response) が出ます。Request URL はモック (http://127.0.0.1:3904) で、応答は 200 と例の注文です。

Swagger UI で GET /orders/orderId の Try it out を実行した後の応答の欄。Request URL の送り先がモックの 127.0.0.1:3904 で、Server response の Code が 200、本文に例の注文が出ている

CORS とモックの設定​

Swagger UI の画面 (http://localhost:3903) とモック (http://127.0.0.1:3904) は、ホストもポートも違う別のオリジンです。ブラウザは、別のオリジンへ送るリクエストのうち、Content-Type: application/json の POST のように単純でないものの前に、送ってよいかを OPTIONS で確かめます (preflight)。オリジンと CORS の仕組みは、Web エンジニアの基礎のオリジンと CORSの章にあります。

Prism は、既定でどの preflight にも 204 で応じ、すべてのオリジンとメソッドを許すヘッダを付けます。仕様に OPTIONS の操作が無くても、仕様に無いパスでもそうします (CORS)。ブラウザが送る preflight を curl で真似ます。

curl -s -i -X OPTIONS http://127.0.0.1:3904/orders \
-H 'Origin: http://localhost:3903' \
-H 'Access-Control-Request-Method: POST' \
-H 'Access-Control-Request-Headers: content-type'
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://localhost:3903
Access-Control-Allow-Headers: content-type
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: *
Access-Control-Allow-Methods: POST
Vary: origin
Content-Length: 0
Date: Sat, 31 Oct 2026 09:00:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5

頼んだオリジン・メソッド・ヘッダを、そのまま許すと返しました。この処理は prism mock --cors=false で止められます。止めたモックに同じ preflight を送ると、注文の API の仕様には OPTIONS の操作が無いので、405 (…#NO_METHOD_MATCHED_ERROR) が返りました。Origin を付けた GET は 200 で返りましたが、Access-Control-Allow-Origin が付きません。CORS が遮るのは、別のオリジンの応答を画面が読むことで、リクエストを送ることそのものではありません (上の CORS の章)。ブラウザは、preflight が通らない JSON の POST は送らず、送った GET の応答は Swagger UI に渡しません。

Swagger UI の CORS の文書は、画面からリクエストのヘッダを送るとき、そのヘッダの名前が API の側の Access-Control-Allow-Headers に入っている必要があると書いています (CORS and Header Parameters)。Prism は頼まれたヘッダをそのまま許すので、モックではこの点で止まりません。第 2 部で作るサーバーを画面から呼ぶときは、許すオリジンとヘッダを、サーバーの側で決めることになります。

Try it out の画面で値を入れられるのは、仕様に書いたパラメータと本文です。Prefer は仕様に無いので、画面からは応答を選べず、成功の応答 (と、検証に落ちたときの 400) だけを見られます。Swagger UI には、送る前のリクエストを書き換える関数を初期化で渡す設定 (requestInterceptor) もありますが (Configuration)、この章では使いません。誤りの応答を見るのは、curl か Bruno です。

Servers の欄のもう 1 つの選択肢 / は、仕様が書いた API の場所で、Swagger UI を配っている配信のサーバー自身に解決されます。これを選んで Execute すると、配信のサーバーが 404 か 405 を返します。注文の API の誤りではありません。

Prism の CORS の処理は、手元で画面から呼ぶためのものです。頼まれたオリジンを何でも許し、Access-Control-Allow-Credentials: true も付けます。本番の API で同じ設定にすると、どのサイトの画面にも、利用者の資格情報 (クッキーなど) を付けたリクエストの応答を読ませることになります。本番で許すオリジンの決め方は、上の CORS の章を見てください。

Postman に置き換えるなら​

手でリクエストを送る道具には、Postman もあります。Bruno の代わりに Postman を使うときに違う点を、保存の形・同期・CLI・料金で並べます。

観点BrunoPostman
保存の形コレクションをフォルダの中のプレーンテキストのファイル (OpenCollection YAML) で持つ (OpenCollection YAML)サインインして使うと、作業は Postman Cloud に置かれる。コレクションは JSON に書き出せる (Exporting data)。今のコレクションの形式 3.0.0 は、ディスクの上の複数の YAML のファイルとして定める (Collection schemas)
同期オフラインだけで動き、クラウドの同期を足す予定は無いと README に書いている (readme)。共有はリポジトリの Git で行う変更はアカウントに結び付いた端末へ Postman Cloud を通して同期される (Syncing)。デスクトップの版の Native Git で、プロジェクトのフォルダのファイルとして持つこともできる (Native Git)
CLI@usebruno/cli の bru runPostman CLI。Newman は 2.1.0 の形式のコレクションは回せるが、3.0 のコレクションは回せない (Collection schemas)
料金アプリと CLI は無料で使える。アプリの Git の画面での commit と push は Pro か Ultimate (Git Integration)Free は 1 人用。共同作業は Team から (ユーザーあたり月 $19、年払い) (Pricing)

このガイドで Bruno を選んだのは、コレクションをサンプルリポジトリの中に置き、仕様と同じ commit で直せるからです。Postman でも、Native Git を使えば同じ形に近づけられます。チームが Postman の共有のワークスペースで仕様とコレクションを管理しているなら、そちらに合わせる理由になります。そのときは、コレクションをリポジトリに書き出して CI の Postman CLI で回すか、Postman の中で回すかを決めておかないと、どちらが正本か分からなくなります。

モックで分からないこと​

この章のモックで確かめたのは、仕様に書いた形です。次のことは、モックでは分かりません。

  • 状態が変わること: 注文を作ると取得できること、在庫が減ること。モックは何も覚えない
  • 仕様のスキーマに書けない決まり: 同じ商品の重なり、在庫不足、登録されていない商品
  • 誤りの中身: どの誤りを送っても、本文は仕様の最初の例。誤りを確かめる順や、最初に見つけた誤りを返すことは確かめられない
  • 操作の外の失敗の形: 一覧に無いパス・405・406 の本文と Allow
  • サーバーにしか無い振る舞い: 注文日時を受け付けた時刻にすること、注文 ID の作り方、速さ

これらは、第 2 部で仕様からサーバーを実装し、実装が仕様と受け入れ条件に合うかをテストで確かめるときに扱います。この章の Bruno のコレクションも、送り先の環境を足せば、実装したサーバーへそのまま向けられます。

見直しで仕様を直して回し直す​

モックと Bruno と Swagger UI で仕様を使うと、読むだけでは気づかなかったことが見つかります。この章では、servers の description が、利用者の目に触れていることに気づきました。

12 章で書いた description (「API を置く場所はまだ決めていない。servers を省いたときの既定と同じ。」) は、仕様を書く人に向けた注記でした。この値は、Swagger UI のサーバーの選び方の欄に出ます。12 章の仕様 (rest-12-r2) を Bruno で読み込むと、環境の名前とファイル名が API を置く場所はまだ決めていない。servers を省いたときの既定と同じ。 になりました。利用者が読む説明として、何を指すかを書く文に直しました。

servers:
- url: /
description: 仕様を配っているサーバーと同じオリジン

仕様を直したら、モックを起動したまま、lint で検査してから束ね直します。

npm run lint
npm run bundle

モックは起動し直さなくてかまいません。Prism は読んだ文書の変更を見張り、変わると HTTP のサーバーを起動し直します (Auto Reloading)。npm run bundle で dist/openapi.yaml を作り直すと、動いているモックの端末に、起動の表示がもう一度出ます。そのあと npm run bruno:mock を回せば、直した仕様でもう一度確かめられます。

最後に、2 つのモック (npm run mock と npm run mock:dynamic) と Swagger UI の配信のサーバーを Ctrl+C で止めてから、テストを回します。テストは、記事の例と同じポートで自分のモックと配信のサーバーを起動し、ポートが使われていると失敗にして止まるからです。

npm run verify

見直しの回し方をまとめると、次の順です。

  1. モックや Bruno で気づく
  2. openapi/ を直す
  3. npm run lint
  4. npm run bundle (動いているモックが読み直す)
  5. npm run bruno:mock
  6. 2 つのモックと配信のサーバーを止めて npm run verify

気づいたことが仕様でなく要件の誤りなら、上の受け入れ条件の直しのように、要件の文書から直します。

実務で効く注意点​

Prism は JSON Schema 2020-12 のキーワードを見落とすことがある​

Prism の issue #2797 は、OpenAPI 3.1 の文書でも、Prism が 2020-12 にしか無いキーワード (unevaluatedProperties・prefixItems など) を確かめずに飛ばすと報告しています。報告は、各スキーマに $schema が無いと Prism が draft-07 の検証器を選ぶことを原因に挙げています。

第 2 部への橋渡しとして、2020-12 のキーワードを使った試しの仕様を Prism 5.16.0 に読ませました。文書の最上位に jsonSchemaDialect が無いと、dependentRequired・unevaluatedProperties・minContains に反するリクエストは受け付けられました。prefixItems と items: false を並べた配列は、合うリクエストまで断られました。各スキーマに 2020-12 の $schema を書いても、結果は同じでした。jsonSchemaDialect に 2020-12 の URI (https://json-schema.org/draft/2020-12/schema) を書くと、type の配列の null を含む 5 つのどれも、合うリクエストを受け付けて反するリクエストを断りました。試した版では、効いたのはスキーマごとの $schema でなく、文書の jsonSchemaDialect でした。

この章の注文の API の仕様は、12 章のガイドラインで、draft-07 と 2020-12 で同じに働くキーワードだけを使うと決めたので、この問題に当たりません。2020-12 にしか無いキーワードを使う仕様をモックで確かめるなら、jsonSchemaDialect を書き、反するリクエストが断られることを、使うキーワードごとに 1 度確かめてください。Prism は、スキーマを検証器に読ませられないときも、誤りを出さずにリクエストを受け付けます (検証の失敗を違反なしとして扱う。validators/utils.ts の validateAgainstSchema)。合うリクエストが通ることだけでは、確かめになりません。

値を作る形の値は、仕様に合うとは限らない​

値を作る形のモックで注文の表現を 20 回取り、仕様のスキーマで確かめると、20 回とも注文日時 (placedAt) が外れました。仕様は placedAt に format: date-time と、秒の小数を 3 桁にそろえる pattern を並べて書いています。Prism 5.16.0 が作った値は 7348-12-31T21:59:51.0Z のように date-time の形で、秒の小数が 3 桁でないので pattern に合いませんでした。注文明細は 100 個近く並び、金額は 2 の 53 乗に近い値になり、スキーマに無いキーも足されます。問題の詳細の応答 (404 と 400) は、20 回とも仕様に合いました。

Prism 自身は、この食い違いに気づいています。値を作る形の応答には、外れた所を書いた sl-violations ヘッダが付き、--errors を付けて起動すると、外れた応答は 500 (…#VIOLATIONS) に変わります。値を作る形のモックで画面を確かめるときは、sl-violations を見るか --errors を付けて、仕様に合わない値で画面を作っていないかを確かめてください。

検証に落ちたリクエストに返る例は、例の並びで決まる​

上で見たとおり、検証に落ちたリクエストには、400 の応答の最初の例が返ります。注文するの 400 の例は invalid-request・unknown-product・insufficient-inventory の順に並べてあるので、形の誤りに形の誤りの例が返ります。例の並びを変えて insufficient-inventory を先にすると、メールアドレスの無い注文に「在庫が足りない」の本文が返るようになります。仕様の例を足したり並べ替えたりするときは、モックの応答も変わることを確かめてください。

まとめ​

  • 束ねた仕様から Prism でモックを動かした。モックは仕様の例を返し、リクエストの中身を応答に使わず、状態を持たない
  • Prefer の code と example で、返す応答を選べる。Accept が application/json だけだと、Prefer で誤りの応答は選べない
  • Prism はリクエストを仕様のスキーマで確かめる。検証に落ちたリクエストには 400 の最初の例を返し、誤りの中身は sl-violations に出す。操作の外の失敗の本文は、10 章の決まりと違う
  • 値を作る形のモックは、値に頼らない作りを確かめるのに使う。テストは値でなく、仕様のスキーマで応答を確かめる
  • 受け入れ条件のうち、例の値と比べられるものと、スキーマで断れるものを Bruno のリクエストにし、確かめられないものは理由とともに表にした。表とコレクションと要件の文書の対応をテストで確かめる
  • Swagger UI の配信のサーバーが、配る仕様の servers にモックを足し、Try it out からモックへ送れるようにした。別のオリジンへのリクエストは、Prism の既定の CORS の処理が受ける
  • モックと道具で仕様を使って見つけたことを、仕様と要件に戻して直し、回し直した

次に読む​

練習問題​

1. 画面を作る人から「在庫が足りないときの画面を、モックを相手に作りたい」と頼まれました。モックからその応答を受け取るには、どうリクエストを送りますか。また、Bruno のコレクションの在庫不足の受け入れ条件に、同じやり方を使わないのはなぜですか。

解答例

Prefer: code=400, example=insufficient-inventory を付けて、注文するを呼びます。Accept には application/json, application/problem+json を入れます。application/json だけだと、Prism は 400 の本文 (application/problem+json) を選べずに最も小さい 2xx (201) に戻ります。201 には insufficient-inventory の例が無いので、Prism の 500 が返ります。

Bruno の受け入れ条件に同じやり方を使うと、モックはリクエストの中身によらず、頼んだ例を返します。頼んだ数量にも、リクエストが仕様に合うかにも関わらず在庫不足の例が返るので、assert は必ず通ります。それでは受け入れ条件を確かめたことになりません。サーバーは Prefer を見ないので、同じリクエストを残しても、サーバーを実装した後に何を確かめているかが変わります。在庫不足は、サーバーを実装してから、在庫を持つ状態で確かめます。

2. 第 2 部でサーバーを実装し、手元の http://127.0.0.1:3000 で動くようになったとします。この章の Bruno のコレクションと docs/getting-started.md の表を、どう変えますか。変えた後に、どのテストが何を確かめるかも説明してください。

解答例

コレクションには、実装したサーバーの環境 (environments/local.yml に baseUrl: http://127.0.0.1:3000) を足します。表で「—」にしていた 5 つの受け入れ条件 (在庫不足 2 つ・登録されていない商品・同じ商品の重なり・無い注文 ID) のリクエストを足し、表の列を指すパスに変えます。モックの環境では確かめられないので、モックの環境で回すリクエストと、サーバーの環境で回すリクエストを、タグで分けることになります (bru run の --tags と --exclude-tags)。フォルダで分けると、フォルダの名前がストーリーの名前と同じことを確かめる test/bruno.test.ts の it も直すことになります。あわせて、モックでは書かなかった assert (誤りの errors の pointer や、在庫不足の productIds) を、サーバーの環境で回すリクエストに足します。在庫が減ること・変わらないことは、1 周目の API に在庫を読む操作が無いので、Bruno のリクエストにはできません。表のその部分は、実装のテストで確かめる行として残ります。

表の行の数と順は変わらないので、test/bruno.test.ts の「表の行が受け入れ条件と同じものを同じ順に持つ」は通ったままで、「表が指すリクエストがその受け入れ条件の名前を持つ」と「どのリクエストも表から指されている」が、足したリクエストと表の食い違いを止めます。「モックで確かめられないこと」の列は、モックの環境では確かめないことの説明として残るので、列の名前と中身も見直します。

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

値を作るモックの応答を、仕様のスキーマで確かめる処理です。記事の curl の出力からステータスコード・Content-Type・本文を読み、メソッドとパスで仕様の操作を探して、応答の本文のスキーマで確かめます。

/*
* 値を作るモック (Prism の --dynamic) の応答を、値でなく仕様のスキーマで確かめる処理。
* 記事の curl (-i -w '\n%{http_code}\n' の形) の出力から、ステータスコード・Content-Type・本文を読み、
* curl のメソッドと URL のパスで仕様の操作を探し、その応答の本文のスキーマで本文を検証する。
* どの段でもスキーマが見つからなければ食い違いとして返す。空のスキーマで検証して通ることを防ぐため。
*/
// ...
/**
* 仕様から、その応答の本文のスキーマを探す。見つからなければ、どの段で見つからないかを文で返す。
* 応答のキーは、ステータスコードそのものか範囲 (4XX など) を探す。default は探さない
* (default に当たると、仕様に無いステータスコードの応答が通ってしまうため)。
*/
function findResponseSchema(spec: unknown, request: CurlRequest, response: CurlResponse): { schema: unknown } | { problem: string } {
const where = `${request.method} ${request.path}`;
const paths = isRecord(spec) ? spec.paths : undefined;
// 変数の少ないテンプレートを先にする (静的なパスを、同じ形の変数のパスより先に当てる)。
const templates = entries(paths)
.filter(([template]) => matchesTemplate(template, request.path))
.sort(([a], [b]) => (a.match(/\{/g)?.length ?? 0) - (b.match(/\{/g)?.length ?? 0));
if (templates.length === 0) return { problem: `${where}: 仕様にこのパスが無い` };
const [template, item] = templates[0];
const operation = isRecord(item) ? item[request.method.toLowerCase()] : undefined;
if (!isRecord(operation)) return { problem: `${where}: 仕様の ${template} にメソッド ${request.method} が無い` };
const responses = isRecord(operation.responses) ? operation.responses : {};
const code = String(response.status);
const declared = responses[code] ?? responses[`${code[0]}XX`];
if (declared === undefined) return { problem: `${where}: 仕様の ${template} の ${request.method} にステータスコード ${code} が無い` };
const resolved = resolveResponse(spec, declared);
const content = isRecord(resolved) && isRecord(resolved.content) ? resolved.content : {};
if (response.contentType === undefined) return { problem: `${where} の ${code}: 応答に Content-Type ヘッダが無い` };
const media = content[response.contentType];
if (!isRecord(media)) return { problem: `${where} の ${code}: 仕様に ${response.contentType} の本文が無い` };
if (!isRecord(media.schema) || Object.keys(media.schema).length === 0) {
return { problem: `${where} の ${code} の ${response.contentType}: 仕様に本文のスキーマが無い` };
}
return { schema: media.schema };
}

test/snippets.test.ts は、servers.json で spec を書いたサーバー (値を作るモック) への例に、.out でなく .status を求めます。ステータスコードを比べた後に、この処理で本文を確かめます。仕様は、loadSpec と同じくテストの中で一時のファイルに束ねて読みます。最後のテストで、spec を書いたサーバーごとに、本文を確かめた例が 1 つ以上あったことを確かめます。

照合の土台の自己テスト (test/harness.test.ts) は、試しの仕様と試しのサーバーで、合う応答が通ること (静的なパスを先に当てる・範囲のキー 4XX に当てる・部品の応答の参照をたどる) を確かめます。あわせて、次の 9 つがそれぞれの理由で落ちることも確かめます。スキーマに合わない本文・仕様に無いパス・仕様に無いメソッド・仕様に無いステータスコード・default にしか無いステータスコード・Content-Type ヘッダの無い応答・仕様に無い Content-Type・スキーマの無い本文・空のスキーマの本文です。

受け入れ条件の文書と表とコレクションの対応を確かめるテストです。

/*
* Bruno のコレクション (bruno/) が、受け入れ条件の文書 (docs/requirements/stories.md) と、
* 始めるための手順 (docs/getting-started.md) の「受け入れ条件とモック」の表にそろっていることを確かめる。
* 受け入れ条件は、モックで確かめるもの (Bruno のリクエストがある) と、モックで確かめられないもの (表に理由がある) に分ける。
* どちらにも入らない受け入れ条件があると、確かめたつもりで抜けるため。
* 例を返すモックへ実際にリクエストを送って assert が通ることは、記事の例 (snippets の bru run) が確かめる。
* 値を作るモックへ送ると落ちることは、記事の例は終了コードだけを見るので、落ちた理由をこのファイルの最後の it が確かめる。
*/
// ...
it('表の行が、受け入れ条件と同じものを同じ順に持ち、どの行にもモックで確かめられないことが書いてある', () => {
expect(rows.length).toBeGreaterThan(0);
expect(rows.map((row) => row[0])).toEqual(criteria().map((c) => c.name));
for (const row of rows) expect(row[2], row[0]).toMatch(/\S/);
});

it('表が指すリクエストは、その受け入れ条件の名前を持ち、そのストーリーのフォルダにある', () => {
const byPath = new Map(requests().map((r) => [r.path, r]));
const storyOf = new Map(criteria().map((c) => [c.name, c.story]));
for (const [name, cell] of rows) {
if (cell === '—') continue;
const path = cell.replace(/^`|`$/g, '');
const request = byPath.get(path);
expect(request, `${name} の ${path}`).toBeDefined();
expect(request?.name).toBe(name);
expect(request?.folder).toBe(storyOf.get(name));
}
});

it('コレクションのリクエストは、どれも表から指されている', () => {
const found = requests().map((r) => r.path);
expect(found.length).toBeGreaterThan(0);
const pointed = rows.filter((row) => row[1] !== '—').map((row) => row[1].replace(/^`|`$/g, ''));
expect(found.sort()).toEqual(pointed.sort());
});

it('どのリクエストも、ステータスコードを確かめる assert を持つ', () => {
for (const request of requests()) {
expect(
request.assertions.some((a) => a.expression === 'res.status' && a.operator === 'eq' && /^\d{3}$/.test(String(a.value))),
request.path,
).toBe(true);
}
});

この後に、次のことを確かめる it が続きます。

  • 例の商品 ID の表の商品 ID が、examples/ の JSON にある
  • 例の商品 ID の表の商品は、受け入れ条件の前提の価格と税率で、注文の例の同じ商品 ID の注文明細にある
  • Bruno の環境の baseUrl は、例を返すモック (servers.json の ch13-mock) のポートを指す
  • 値を作るモックへのコレクションは、送り先に届いた上で、assert の外れで落ちる

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

Swagger UI の配信のサーバーが配る仕様を作る処理です。

/*
* Swagger UI の Try it out をモックへ送れるよう、配る仕様にだけモックを足す。
* 仕様のファイルには書かない。仕様の servers は API を置く場所を表し、手元のモックの URL は、仕様を読む人の誰にでも当てはまる場所ではないため。
*/
import { parse, stringify } from 'yaml';

/** Prism は 127.0.0.1 で待ち受けるので、localhost (::1 に解決されうる) でなく 127.0.0.1 と書く。 */
export const mockServer = { url: 'http://127.0.0.1:3904', description: 'モック (npm run mock)' };

/**
* servers の先頭にモックを足す (servers が無ければモックだけを置く)。
* 仕様がキーと値の組の文書でないか、servers があって配列でなければ (null を含む)、配らずに例外にする。
* 配信のサーバーが 500 で知らせ、束ね直しの誤りに気づけるようにするため。
*/
export function specForBrowser(text: string): string {
const document: unknown = parse(text);
if (typeof document !== 'object' || document === null || Array.isArray(document)) {
throw new Error('仕様が、キーと値の組の文書でない');
}
const servers = 'servers' in document ? document.servers : [];
if (!Array.isArray(servers)) throw new Error('仕様の servers が配列でない');
return stringify({ ...document, servers: [mockServer, ...servers] });
}

配信のサーバー (tools/swagger-ui/server.ts) は、/openapi.yaml を頼まれるたびに dist/openapi.yaml を読み、この処理を通して配ります。

if (path === '/openapi.yaml') {
let body: string;
try {
body = specForBrowser(readFileSync(spec, 'utf8'));
} catch (error) {
/*
* 束ねる前や dist/ を消した後 (ENOENT) と、束ね直している途中の書きかけのファイル (YAML として読めない) で投げる。
* 先に existsSync で有無を見ても、見た後に消えたときと ENOENT 以外の誤りでは投げるので、ここで捕まえて 500 にする。
*/
const reason = (error as NodeJS.ErrnoException).code ?? (error as Error).message;
return send(res, 500, 'text/plain; charset=utf-8', `dist/openapi.yaml を読めません (${reason})。npm run bundle で作り直してください\n`);
}
return send(res, 200, 'application/yaml', body);
}