microCMSのマネジメントAPI（ベータ）からOpenAPI定義を作成する
X-tech推進本部 黒澤ヘッドレスCMSを使ったWebサイトでは、ヘッドレスCMSから記事データなどを取得し、HTMLなどを生成しています。
HTML生成処理は、ヘッドレスCMSから取得するデータの構造にあわせて作成する必要があります。例えば、ページタイトルを表す文言がヘッドレスCMSではtitleと呼ばれている一方で、HTML生成処理ではpageTitleと呼ばれる想定だった場合、生成されたHTMLにページタイトルが含まれなくなってしまいます。
当社ではヘッドレスCMSの1つであるmicroCMSを使ったプロジェクトが増えており、HTML生成処理が想定するデータの構造を次のように定義しています。
- エンジニアがmicroCMSのデータ定義からOpenAPI定義を作成
- openapi-typescriptを使ってOpenAPI定義をTypeScriptの型に変換
- エンジニアがTypeScriptの型を関連するコード（microCMSからデータをダウンロードする処理など）に反映
本記事では、microCMSのデータ定義からOpenAPI定義を機械的に生成する試みを紹介します。
なお、microCMSのデータ定義はAPIと呼ばれていますが、この記事ではAPIという語を複数の意味で利用しますので、以降では、「データ定義（API）」と記載します。
マネジメントAPIからOpenAPI定義の作成手順例
microCMSではマネジメントAPIを使うことで、データ定義（API）をJSONとして取得できます。
マネジメントAPIからOpenAPI定義を作成する具体的な手順は次の通りです。
なお、マネジメントAPIはベータ版として提供されており、今後の変更によって記事内容が当てはまらなくなる可能性がありますので、ご留意ください。
まず、データ定義（API）の一覧を取得します（GET /api/v1/apis）。Node.jsでのコード例は次の通りです。
const {API_KEY, SERVICE_DOMAIN} = process.env;
const apisUrl = `https://${SERVICE_DOMAIN}.microcms-management.io/api/v1/apis`;
const apisResponse = await fetch(apisUrl, {
method: 'GET',
headers: { 'X-MICROCMS-API-KEY': API_KEY },
});
const apisResult = await apisResponse.json();変数apisResultにはデータ定義（API）の概要が格納されています。
{
"apis":[
{
"name": "API名",
"endpoint": "endpoint",
"type": "list"
}
]
}次に、各データ定義（API）の詳細を取得します（GET /api/v1/apis/{endpoint}）。同じく、Node.jsでのコード例を示します。
for (const api of apisResult.apis) {
const apiUrl = `https://${SERVICE_DOMAIN}.microcms-management.io/api/v1/apis/${encodeURIComponent(api.endpoint)}`;
const apiResponse = await fetch(apiUrl, {
method: 'GET',
headers: { "X-MICROCMS-API-KEY": API_KEY },
});
const apiResult = await apiResponse.json();
}変数apiResultにはデータ定義（API）の詳細が格納されています。
{
"apiFields": [
{
"fieldId": "fieldId",
"name": "フィールド名",
"kind": "text",
"required": true
}
],
"customFields": [
{
"createdAt": "2025-01-02T03:04:05.678Z",
"fieldId": "customFieldId",
"name": "カスタムフィールド名",
"fields": [ ... ],
"position": [ ... ],
"updatedAt": "2026-01-02T03:04:05.678Z",
}
]
}最後に、取得した情報をOpenAPI定義として出力します。出力のイメージを示します。
openapi: "3.0.3"
info:
title: "microCMS API"
version: "1.0.0"
description: "microCMSのマネジメントAPIから生成したコンテンツAPI（GETのみ）"
paths:
/endpoint:
get:
responses:
"200":
description: "API名の一覧"
content:
application/json:
schema:
type: "object"
description: "API名の一覧レスポンス"
properties:
contents:
type: "array"
items:
type: "object"
description: "API名"
properties:
fieldId:
type: "string"
description: "フィールド名（テキストフィールド）"
required:
- "fieldId"なお、実際に生成するOpenAPI定義では複数のYAMLファイルに分割したり、microCMSが自動付与する値を定義に含めたりするなどの調整を行っています。
また、この試みでは次の内容を出力するようにしました。
- コンテンツAPI
- コンテンツ一覧取得API（GET /api/v1/{endpoint}）
- 単一コンテンツ取得API（GET /api/v1/{endpoint}/{content_id}）
- フィールド種類（GET APIのフィールドごとのレスポンス形式）
- テキストフィールド
- テキストエリア
- リッチエディタ
- 画像
- 複数画像
- 日時
- 真偽値
- セレクトフィールド
- コンテンツ参照
- 複数コンテンツ参照
- カスタムフィールド
- 繰り返しフィールド
- ファイル
メリット・デメリット
機械生成によるメリットはいくつかあります。
1つ目はmicroCMSのデータ定義とHTML生成処理との認識相違に気が付きやすくなることです。
以前より、OpenAPI定義からTypeScriptの型を生成し、型チェックによる整合性確認は機械化していました。今回、microCMSのデータ定義（API）をOpenAPI定義に反映する作業を機械化したことで、microCMSでのデータ定義（API）の調整後、すぐにTypeScriptの型チェックを行えるようになりました。
また、OpenAPI定義とプロジェクトの要件に不整合があった場合、これまではmicroCMSのデータ定義（API）が誤っているのか、OpenAPI定義が誤っているのか、両方誤っているのかなどの切り分けが必要でしたが、機械生成によって切り分けが容易になりました。
2つ目はHTML生成処理を作成する際に、データ定義（API）の日本語での名前を確認しやすくなることです。
microCMSではデータ定義（API）の設計にあたって、英数字で設定するフィールドIDと日本語で設定可能な表示名を設定できます。HTML生成処理のコードに記述するのはフィールドIDですので、手でOpenAPI定義を作成する際もフィールドIDを必ず書いていましたが、表示名の記載は任意であり、省略することもありました。
しかし、多くのプロジェクト関係者は表示名でコミュニケーションするため、表示名が確認しやすいに越したことはありません。OpenAPI定義を機械的に生成することで、表示名を常に記載できるようになりました。表示名は、OpenAPI定義から生成したTypeScriptの型にも反映されるため、エディタなどから簡単に確認できます。
機械生成によるデメリットもあります。最も大きいことは柔軟性がないことです。手でOpenAPI定義を作成する際は、人が判断して定義をよしなに分割したりグルーピングしたりできましたが、機械的な生成では実現できていません。
まとめ
本記事ではmicroCMSのマネジメントAPIを利用してデータ定義（API）からOpenAPI定義を機械的に生成する試みを紹介しました。
ヘッドレスCMSのデータ構造とHTML生成処理との整合性を早期に・頻繁にチェックできるようになることで、開発効率と品質の向上につながると考えています。
本記事がmicroCMSによるサイト構築の参考になれば幸いです。