OpenApiドキュメントからMockサーバを立てる

はじめに

OpenApiのドキュメントからMockサーバを立てる方法を記事にします。
今回はPrismいうツールを使ってみます。

手順

インストール

viteやnext.jsでプロジェクトの中で以下のコマンドを実行します。

npm install -D  @stoplight/prism-cli

OpenApiドキュメントの用意

./openapi/openapi.oas3.ymlという名前でドキュメントを作成します。

サンプルで作成したOpenApiのドキュメント

./openapi/openapi.oas3.yml

openapi: "3.0.3"

info:
  title: "サンプルAPI"
  description: "サンプル用のAPIです"
  version: "0.0.1"

servers:
  - url: "http://localhost:8080"
    description: "ローカル環境"
  - url: "https://sample.com"
    description: "本番環境"

tags:
  - name: "users"
    description: "ユーザー情報"

paths:
  "/users":
    get:
      tags: ["users"]
      summary: "ユーザー一覧取得"
      responses:
        "200":
          description: "成功"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
        "500":
          description: "内部エラー"
    post:
      tags: ["users"]
      summary: "ユーザー作成"
      requestBody:
        description: "新規ユーザー情報"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/User"
      responses:
        "201":
          description: "成功"
        "400":
          description: "不正なパラメータ"
        "409":
          description: "パラメータに競合があります"
        "500":
          description: "内部エラー"
  "/users/{discriminator}":
    get:
      tags: ["users"]
      summary: "ユーザー情報取得"
      parameters:
        - name: discriminator
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Discriminator"
      responses:
        "200":
          description: "成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: "不正なパラメータ"
        "404":
          description: "該当ユーザーなし"
        "500":
          description: "内部エラー"
    put:
      tags: ["users"]
      summary: "ユーザー情報変更"
      parameters:
        - name: discriminator
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Discriminator"
      requestBody:
        description: "新規ユーザー情報"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/User"
      responses:
        "204":
          description: "成功"
        "400":
          description: "不正なパラメータ"
        "404":
          description: "該当ユーザーなし"
        "409":
          description: "パラメータに競合があります"
        "500":
          description: "内部エラー"

    delete:
      tags: ["users"]
      summary: "ユーザー削除"
      parameters:
        - name: discriminator
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Discriminator"
      responses:
        "204":
          description: "成功"
        "400":
          description: "不正なパラメータ"
        "404":
          description: "該当ユーザーなし"
        "500":
          description: "内部エラー"

components:
  schemas:
    User:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 24
          example: "ユーザー名"
        email:
          type: string
          format: email
        discriminator:
          $ref: "#/components/schemas/Discriminator"
        note:
          type: string
          maxLength: 256
    Discriminator:
      type: string
      pattern: "^[A-Za-z0-9_]+$"
      maxLength: 24
      minLength: 3

Mockサーバーの起動

npx prism mock ./openapi/openapi.oas3.yml -p 8080

おわりに

OpenApiのドキュメントから簡単にMockサーバーを立てることが出来ました。
レスポンスの複雑な制御はできなかったので、その場合はクライアント側でのMockが必要になりそうです。