現在、APIエンドポイントに個別のMDXページを使用している場合、各ページのカスタマイズ性を保ちながら、OpenAPI仕様からページを自動生成する方式へ移行できます。これにより、保守対象のファイル数を削減し、APIドキュメントの一貫性を高められます。 OpenAPI仕様内で各エンドポイントのメタデータとコンテンツを定義し、ナビゲーション内で任意の位置に配置できます。

​
CLI 移行

mint migrate-mdx コマンドは、MDX のエンドポイントページから自動生成ページへ移行するための推奨手段です。 このコマンドは以下を実行します:
  • docs.json のナビゲーション構造を解析します。
  • OpenAPI のエンドポイントページを生成している MDX ページを特定します。
  • MDX ファイルのコンテンツを抽出し、OpenAPI 仕様の x-mint 拡張に移行します。
  • docs.json を更新し、MDX ファイルではなく OpenAPI のエンドポイントを直接参照するようにします。
  • 元の MDX のエンドポイントファイルを削除します。
すでにエンドポイントに x-mint が定義されており、同じエンドポイント向けのコンテンツを持つ MDX ページもある場合、MDX のコンテンツが既存の x-mint 設定を上書きします。同一エンドポイントに対して内容の異なる複数の MDX ページがある場合、スクリプトは docs.json 内で最後に記載されているページのコンテンツを使用します。移行ツールには、適用前に変更をプレビューする機能はありません。
1

OpenAPI 仕様を準備する

OpenAPI 仕様が妥当で、ドキュメント化したいすべてのエンドポイントを含んでいることを確認してください。移行対象の MDX ページには、エンドポイントを参照する openapi: フロントマターが必要です。
Swagger Editor または Mint CLI を使って OpenAPI ファイルを検証してください。
2

Mint CLI をインストールする

必要に応じて Mint CLI をインストールまたは更新してください。
3

移行コマンドを実行する

mint migrate-mdx

​
手動移行手順

1

OpenAPI 仕様を準備する

OpenAPI 仕様が妥当で、ドキュメント化したいすべてのエンドポイントを含んでいることを確認します。メタデータやコンテンツをカスタマイズしたいエンドポイントには、x-mint 拡張を追加します。詳しくは x-mint extension を参照してください。ドキュメントから除外したいエンドポイントには、x-hidden 拡張を追加します。
Swagger Editor または Mint CLI を使用して OpenAPI ファイルを検証してください。
2

ナビゲーション構造を更新する

docs.json 内の MDX ページ参照を、OpenAPI のエンドポイントに置き換えます。
"navigation": {
  "groups": [
    {
      "group": "API Reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "overview",
        "authentication",
        "introduction",
        "GET /health",
        "quickstart", 
        "POST /users",
        "GET /users/{id}",
        "advanced-features"
      ]
    }
  ]
}
3

古い MDX ファイルを削除する

新しいナビゲーションが正常に動作することを確認したら、不要になった MDX エンドポイントのファイルを削除します。
ナビゲーションにおけるAPIドキュメントの表示方法をカスタマイズできます。

​
混在コンテンツのナビゲーション

自動生成された API ページをほかのページと組み合わせる: 
"navigation": {
  "groups": [
    {
      "group": "API Reference",
      "openapi": "openapi.json",
      "pages": [
        "api/overview",
        "GET /users",
        "POST /users", 
        "api/authentication"
      ]
    }
  ]
}

​
複数のAPIバージョン

タブやグループを使って異なるAPIバージョンを整理します: 
"navigation": {
  "tabs": [
    {
      "tab": "API v1",
      "openapi": "specs/v1.json"
    },
    {
      "tab": "API v2", 
      "openapi": "specs/v2.json"
    }
  ]
}

​
個別の MDX ページを使うべきタイミング

次のような場合は、個別の MDX ページを維持することを検討してください:
  • 各エンドポイントごとに、React コンポーネントや長文の例など、リッチなカスタムコンテンツが必要な場合
  • 固有のページレイアウトが必要な場合
  • 特定のエンドポイント向けに、実験的なドキュメント手法を試したい場合
多くのケースでは、OpenAPI のナビゲーションを使う方が、保守性と一貫性の面で優れています。