スキーマと型を管理する

microCMSのAPIスキーマをmcms-cliで取得してファイルに保存し、前回との差分を確認する方法を説明します。取得した定義からTypeScript型やdraft-07のJSON Schemaを生成し、アプリケーションの型付け、payload検証、フォーム生成、AIへ渡す構造定義に利用する流れを紹介します。

mcms-cliでは、microCMSのAPIスキーマを取得し、変更の検査や型生成に利用できます。

スキーマを取得する

microcms schema pull \
  --out microcms-schema.json \
  --json

特定のendpointだけを対象にすることもできます。

microcms schema pull \
  --endpoints blogs \
  --out blogs-schema.json \
  --json

JSONファイルからAPIを作成する

APIスキーマを含むJSONファイルから、新しいAPIを作成できます。microcms api createはManagement APIを使います。--name、--endpoint、--typeを指定すると、ファイルの基本設定を補完または上書きできます。

microcms api create \
  --file articles-api.json \
  --name articles \
  --endpoint articles \
  --type list \
  --dry-run \
  --json

dry-runではAPIスキーマとカスタムフィールドの構造を検証します。結果を確認してから--dry-runを外し、APIを作成します。追加料金を許可する場合だけ--allow-additional-chargeを指定します。

コマンドリファレンスにオプションをまとめています。

スキーマの差分を検査する

保存してあるbaselineと現在のスキーマを比較します。

microcms schema diff \
  --baseline microcms-schema.json \
  --json

CIで差分を終了コードへ反映したい場合は、--exit-codeを追加します。

microcms schema diff \
  --baseline microcms-schema.json \
  --exit-code \
  --json

TypeScript型を生成する

取得済みスキーマから型を生成できます。

microcms types generate \
  --schema microcms-schema.json \
  --out microcms-types.d.ts \
  --json

取得と型生成をまとめる場合はtypes syncを使います。

microcms types sync \
  --out microcms-types.d.ts \
  --schema-out microcms-schema.json \
  --json

JSON Schemaへ変換する

microcms schema pull \
  --format json-schema \
  --include-extensions \
  --out schema.json \
  --json

生成されるJSON Schemaはdraft-07です。payload検証、フォーム生成、AIに渡す構造定義などに利用できます。

複雑なリレーションやリピーターを含む高度な型生成が主目的の場合は、READMEで案内されている専用CLIも比較してください。

関連ページ

• コマンドリファレンス
• AI・CIから利用する