京都のシステム開発・ホームページ制作会社　株式会社Nextat（ネクスタット）

こんにちは、さわちゃんです。

今回はOpenAPI + Prismでモックサーバを建てているとき、複数のレスポンスを出し分ける方法について書いていきます。
 

開発環境

OpenAPI: 3.1.0
@stoplight/prism-cli: 4.10.1
Node.js: 16.13.1
Yarn: 1.22.18

具体的な環境構築手順については割愛しますが、この記事においてはDocker等を使わずローカルで環境構築しています。
その場合、Prismをインストールするだけです。
 

yarn add @stoplight/prism-cli

STEP1 Examplesを複数用意しよう

まず先に今回用意したOpenAPIによるAPI定義をお見せします。

openapi.yaml

openapi: 3.1.0
info:
  title: Prismでレスポンスを出し分けよう
  version: '1.0'
servers:
  - url: 'http://localhost:4010'
paths:
  /users:
    get:
      summary: ユーザー一覧API
      description: ユーザー一覧を取得する
      operationId: index_users
      tags:
        - users
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  list:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          description: ユーザーID
                          type: integer
                        name:
                          type: string
                          description: ユーザー名
                      required:
                        - id
                        - name
                required:
                  - list
              examples:
                case1:
                  summary: ケース1
                  value:
                    - id: 1
                      name: ユーザー１
                    - id: 2
                      name: ユーザー2
                case2:
                  summary: ケース2
                  value:
                    - id: 3
                      name: ユーザー3
                    - id: 4
                      name: ユーザー4

注目ポイントはexamples以下の部分です。
今回はcase1とcase2の2つのパターンを用意しましたが、このような形でexamplesに複数のパラメータを用意し、value以下に出力してほしい値をそれぞれ記載することで、レスポンスの選択肢を作ることができます。

試しにSwagger Editorで見てみましょう。
https://editor.swagger.io/
   
このようにしてレスポンスのExamplesを複数定義することができました。
OpenAPIによるAPI定義についてはこれで作業完了です。

参考
https://swagger.io/docs/specification/adding-examples/

 

STEP2 Prismを使ってモックサーバを建てよう

openapi.yamlというファイル名でOpenAPIを記述したので、以下のコマンドで起動することができます。
 

prism mock ./openapi.yaml

これでモックサーバの起動は完了です。
 

STEP3 レスポンスを出し分けよう

いよいよ本題です。
STEP1でExamplesを複数定義しましたが、特に何も指定せずにAPIコールした場合、一番目に定義したExamples(case1の方)が返ってきます。
 

$ curl -X GET 'http://localhost:4010/users'

=> [{"id":1,"name":"ユーザー１"},{"id":2,"name":"ユーザー2"}]

ではcase2の方をレスポンスしてほしいときはどうすればよいのでしょうか？

答えとしては
APIコールする際のHTTPリクエストのPreferヘッダーにexampleのキーをセットする
です。

具体的には以下のような形になります。
 

curl -X GET 'http://localhost:4010/users' -H 'Prefer:example=case2'

=> [{"id":3,"name":"ユーザー3"},{"id":4,"name":"ユーザー4"}]

これで複数用意したExamplesをクライアント側から出し分けることができるようになりました。
 

おわりに

これを知らないと、わざわざOpenAPIのexampleを必要なケースが出るたびに書き換えて使う・・・みたいな面倒なことになってしまいます。

動作確認をするときなどに重宝するので、あらかじめ予想されるケース（データがないときのテストや閾値テストなど）がある場合、ここのExamplesをたくさん書いておくと後で楽になるのかもしれません。

以上です。お疲れさまでした。