OpenAPI Document（Swaggerファイル） + PrismでAPIモックサーバを立てる

はじめに

OpenAPI Document（Swaggerファイル）とは、API仕様書を記述するためのファイル形式です。具体的には、APIのインターフェース定義やリクエスト/レスポンスで使われるデータの構造を、JSONまたはYAMLで記述したものです。

そこに、Prismというツールを使うことで、APIモックサーバーを立てることができます。これによって、例えば開発中のマイクロサービスのAPIとの連携処理を実装したい場合、モックサーバーのレスポンスをベースに開発を進めることができます。

以下に具体的な手順を記載します。

1. OASファイル作成

OASファイルを作成します。エディタは、Swagger EditorかVSCode拡張のSwagger Tools + Swagger Viewerがおすすめです。ここでは、ユーザー情報を取得するAPIを最小構成で定義します。各項目の意味は推測できると思うので説明を省きます。詳しく知りたい方はこちらを参照してください。

openapi: 3.0.3
info:
  title: FooマイクロサービスAPI
  version: "1.0.0"
paths:
  /user/get:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
      responses:
        "200":
          description: ユーザー情報を含むJSONオブジェクトを返却します。
          content:
            application/json:
              schema:
                type: object
                properties:
                  userName:
                    type: string

これを、foo.ymlという名前で保存します。

2. Prismをインストール

Prismはnodeで動作するので、まずnodeをインストールします。本記事では、Windowsにインストールする前提で進めます。実践される場合はご自身の環境に合わせてインストールしてください。

Windowsには、公式のインストーラを使ってインストールしてください。

nodeをインストールしたら、Prismをインストールします。

npm install -g @stoplight/prism-cli

3. Prism実行

prismコマンドを実行します。デフォルトでは、ポート4010でホストされます。

prism mock foo.yml
[9:56:27] » [CLI] ...  awaiting  Starting Prism…
[9:56:28] » [CLI] i  info      POST       http://127.0.0.1:4010/user/get
[9:56:28] » [CLI] ►  start     Prism is listening on http://127.0.0.1:4010

Postmanなどのクライアントツールでリクエストを送ると、結果が返ってきます。

4. Exampleを記載

stringのフィールドにstringという文字列が入っていても一応テストはできますが、より実際のレスポンスに近づけるためにexampleを記載しましょう。

openapi: 3.0.3
info:
  title: FooマイクロサービスAPI
  version: "1.0.0"
paths:
  /user/get:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
      responses:
        "200":
          description: ユーザー情報を含むJSONオブジェクトを返却します。
          content:
            application/json:
              schema:
                type: object
                properties:
                  userName:
                    type: string
                    example: "testuser"

すると、レスポンスのフィールドにexampleの値がセットされます。

おわりに

チームでの開発では、各デベロッパーのローカル環境にそれぞれモックサーバーを立てるのではなく、モックサーバー用のクラウドサーバーでPrismをホストするのが良いと思います。

活用していただき、良きインターフェース開発ライフを！