Prismを使ってOpenAPI定義をもとにモックサーバを作成してみる
概要
OpenAPI定義書をもとに、Prismを使ってモックサーバを立ち上げます。
Prism利用にあたっては、dockerを使います。
Prismとは
Prismは、OpenAPIなどのAPI仕様ドキュメントを基にモックサーバを立てるためのサービスです。
API仕様ドキュメントがあれば、即座にモックサーバを立てることができるため、例えば以下のような恩恵があります。
- バックエンドAPIが完成していなくても、フロントエンド開発を進めることができる
- 設計段階からユーザーのフィードバックを得られる(早期にフィードバックを得ることで、実装後の手戻りを減らせるため、開発効率アップ)
やってみる
docker-compose.ymlの準備
dockerでPrismを利用するため、docker-compose.ymlファイルを用意します。
services:
prism:
image: stoplight/prism:4
platform: linux/amd64
command: mock -h 0.0.0.0 /openapi.yaml
volumes:
- ./openapi.yaml:/openapi.yaml
ports:
- "4010:4010"
OpenAPI定義ファイルの準備
下記のようなOpenAPI定義ファイルを準備します。
openapi: 3.0.0
info:
title: Sample API
version: 1.0.0
paths:
/users:
get:
summary: Returns a list of users.
responses:
'200':
description: A JSON array of users with details
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
age:
type: integer
gender:
type: string
example:
- name: 桑原 将志
age: 31
gender: male
- name: 筒香 嘉智
age: 32
gender: male
- name: 牧 秀悟
age: 26
gender: male
以下は、このOpenAPI定義をプレビューしたものです。
※ OpenAPI定義のプレビューには、OpenAPI (Swagger) Editor(42crunch.vscode-openapi)というVSCodeの拡張機能を使用。
とりあえずモックサーバを動してみる
コンテナを起動する
docker-compose.ymlが配置されたディレクトリに移動して、コンテナを起動しておきます。
$ docker-compose up -d
ブラウザで動作確認
今回、ポート番号は4010を指定していますので、対象となるエンドポイントはhttp://localhost:4010/usersです。
ブラウザにhttp://localhost:4010/usersを入力します。
すると、モックサーバからOpenAPI定義書に記載のレスポンスが返却されていることが確認できました。
パスパラメータを使用するケース
users/{id}のようにパスパラメータを指定して、1件取得するケースもやってみます。
OpenAPI定義に以下のエンドポイントを追加します。
+ /users/{id}:
+ get:
+ summary: Returns a user by ID.
+ parameters:
+ - in: path
+ name: id
+ required: true
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: A single user with details
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ id:
+ type: integer
+ name:
+ type: string
+ age:
+ type: integer
+ gender:
+ type: string
+ example:
+ id: 1
+ name: 桑原 将志
+ age: 31
+ gender: male
ランダムなデータを返す
OpenAPI定義のexampleに記載した固定データではなく、ランダムなデータを生成して返却することも可能です。
OpenAPI定義を以下のように変更します。
openapi: 3.0.0
info:
title: Sample API
version: 1.0.0
paths:
/users:
get:
summary: Returns a list of users.
responses:
'200':
description: A JSON array of users with details
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
+ example: 1
name:
type: string
+ pattern: '^[A-Z]{1}[a-z]{3,7}$'
age:
type: integer
+ minimum: 0
+ maximum: 100
gender:
type: string
+ enum: [male, female]
- example:
- - name: 桑原 将志
- age: 31
- gender: male
- - name: 筒香 嘉智
- age: 32
- gender: male
- - name: 牧 秀悟
- age: 26
- gender: male
この状態で、http://localhost:4010/usersを叩いてみますが、ランダムなデータは生成されません。何度やっても、同じ値が返ってきます。
動的なデータを生成を行う場合は、--dynamicオプションを使います。そのため、docker-compose.ymlにも修正が必要です。
services:
prism:
image: stoplight/prism:4
platform: linux/amd64
+ command: mock -h 0.0.0.0 /openapi.yaml --dynamic
- command: mock -h 0.0.0.0 /openapi.yaml
volumes:
- ./openapi.yaml:/openapi.yaml
ports:
- "4010:4010"
上記の変更を加えた上で、コンテナを起動し直し、ブラウザにhttp://localhost:4010/usersを入力します。
すると、OpenAPI定義書に指定した範囲内で、動的にランダムデータが生成されて返却されることが確認できました。
再度、http://localhost:4010/usersを実行すると、値やユーザーオブジェクトの数が変わっていることが分かります。
最後に
以上、prismを使ってモックサーバを立ててみました。
他にも、
- 異常系(404や500など)を返すようにする
- リクエストに対するバリデーションを行う
- レスポンスを遅延させる
など、いろんなことができそうです(未確認ですが)。
またprismを深掘りする機会があれば、もっと試してみたいと思います。
Discussion