MockAPI-PHP

OpenAPI スキーマ自動生成機能

バージョン1.2以降にて responses/{エンドポイントパス}/{メソッド}/{ステータス名}.json に配置されたJSONレスポンスファイル群から OpenAPI 3.0 スキーマを自動生成する機能が追加されました。

実行方法

CLI（コマンドライン）

php generate-schema.php [format] [title] [version]

• format （任意）：出力フォーマット（json または yaml）デフォルト：yaml
• title （任意）： OpenAPI のタイトル
• version （任意）： OpenAPI のバージョン

例：

php generate-schema.php yaml "My Awesome API" "2.0.0"

Web（ブラウザ経由）

GET /generate-schema.php?format=json&title=My+Awesome+API&version=2.0.0

出力ファイル

schema/openapi.yaml または schema/openapi.json にスキーマが生成されます。

バリデーション

各 JSON レスポンスファイルは、独自に生成されたスキーマに対して JSON Schema バリデーションを実施します。 不正な構造のレスポンスがあれば logs/validation-error.log にエラーメッセージを出力し、処理を中断します。

example 自動登録

生成される OpenAPI スキーマには、example として元となった JSON の内容が登録されます。

• 配列の場合、最初の要素のみ が example に含まれます（肥大化回避のため）。
• ネストされた配列・オブジェクトにも再帰的に適用されます。

環境変数（.env）

.env に以下の環境変数を定義することで、デフォルト動作をカスタマイズできます。

LOG_DIR=./logs
SCHEMA_DIR=./schema
SCHEMA_FORMAT=yaml
SCHEMA_TITLE=MockAPI-PHP Auto Schema
SCHEMA_VERSION=1.0.0

※ 環境変数で定義された SCHEMA_FORMAT SCHEMA_TITLE SCHEMA_VERSION よりもパラメータで指定した値が優先されます。

スキーマ自動生成の活用シーン

• 手動で OpenAPI スキーマを書く手間を省きたい場合
• 実装より先にモックを作る「APIファースト」な開発方針に沿うケース
• 他ツール（Prism, SwaggerUI など）との連携に使いたい場合
• 自動テストとの連携でスキーマ整合性を確認したいとき

CI/CD での自動スキーマ生成例（GitHub Actions）

.github/workflows/generate-schema.yml

name: Generate OpenAPI Schema

on:
  push:
    paths:
      - 'responses/**'
      - 'generate-schema.php'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
      - run: composer install --no-dev
      - run: php generate-schema.php json
      - name: Upload schema
        if: hashFiles('schema/openapi.yaml') != ''
        uses: actions/upload-artifact@v4
        with:
          name: openapi-schema
          path: schema/openapi.json

これにより、レスポンス変更時に常に最新のスキーマが生成・保存されるようになります。