はじめに

OpenAPI に複数のレスポンス例を書いて、prism で mock API を立てて、レスポンスを切り替えながら GUI 開発をすると便利と実感したので共有します。

検証に使ったコードはこちらに置いてあります。

目次

OpenAPI Specification の仕様
Prism の仕様
開発時に行うこと
用意したコード
考察
検証の元になった記事
最後に

OpenAPISpecificationの仕様

OpenAPI Specification は複数のレスポンス例を書くことができます。swagger UI を使えば複数のレスポンス例を切り替えて表示できます。

Prism の仕様

Prism は OpenAPI に沿った mock server を立ててくれるツールです。Prism は request header に Prefer を入れることで response 内容を切り替えてくれます。例えば、"Prefer: example=example1" と指定すると example1 の response body を返してくれます。また、"Prefer: code=500" と指定すると status code 500 に記載してある example の response body を返してくれます。

開発時に行うこと

OpenAPI に欲しいケースのレスポンス例を複数追加します。
Prism で mock server を立ち上げます。
request header に Prefer を付けてレスポンスを切り替えます。
- local動作確認でmockが欲しい場合は load balancer(Caddy) を経由して header を追加します。

以下は、mock API を直接叩いた場合と、load balancer(Caddy)で header を追加した場合のレスポンスが異なる例です:

$ curl http://localhost:4010/api/users -s | jq       
{
  "users": []
}

$ curl http://localhost:8000/api/users -s | jq
{
  "users": [
    {
      "id": 1,
      "name": "John Doe",
      "mailAddress": "john.doe@example.com"
    },
    {
      "id": 2,
      "name": "Jane Doe",
      "mailAddress": "jane.doe@example.com"
    }
  ]
}

用意したコード

Caddyfile

http://localhost:80 {
    # API の定義を記載 start

    @api_users_get {
        path /api/users
        method GET
    }
    # API の定義を記載 end

    # レスポンス切り替える対象を記載 start
    handle @api_users_get {
        reverse_proxy http://api-mock:4010 {
            header_up Prefer "example=ManyUserResponse"
        }
    }
    # レスポンス切り替える対象を記載 end

    handle {
        reverse_proxy http://api-mock:4010
    }
}

docker-compose.yaml

version: '3.9'

services:
  api-mock-proxy:
    image: caddy:2
    restart: always
    ports:
      - "8000:80"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
    depends_on:
      api-mock:
        condition: service_started

  api-mock:
    image: stoplight/prism:4
    ports:
      - "4010:4010"
    volumes:
      - ./openapi.yaml:/openapi.yaml
    command:
      mock /openapi.yaml -h 0.0.0.0 -p 4010

  swagger:
    image: swaggerapi/swagger-editor
    ports:
      - "8080:8080"
    volumes:
      - ./openapi.yaml:/openapi.yaml
    environment:
     - SWAGGER_FILE=/openapi.yaml

openapi.yaml

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
paths:
  /api/users:
    get:
      summary: Get list of users
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
              examples:
                emptyUsersResponse:
                  summary: No users
                  value:
                    users: []
                oneUserResponse:
                  summary: One user
                  value:
                    users:
                      - id: 1
                        name: John Doe
                        mailAddress: john.doe@example.com
                ManyUserResponse:
                  summary: Multiple users
                  value:
                    users:
                      - id: 1
                        name: John Doe
                        mailAddress: john.doe@example.com
                      - id: 2
                        name: Jane Doe
                        mailAddress: jane.doe@example.com
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: Internal server error
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: John Doe
        mailAddress:
          type: string
          example: john.doe@example.com

考察

mswjs でレスポンスを変更してテストする方法もあるみたいです。しかし、本記事の方法だとOpenAPI定義書に複数のレスポンス例が書かれて良いです。

検証の元になった記事

最後に

最後までお読み頂きありがとうございます。励みになるので、良かったらいいね 👍 をお願い致します。