Mintlify は、OpenAPI 3.0 および 3.1 仕様書（JSON または YAML 形式）から、洗練されたインタラクティブな API ドキュメントを自動生成するプラットフォームです。開発者やテクニカルライターがパラメータ一覧、ヘッダー情報、レスポンススキーマを手動でテーブル化する必要はありません。Mintlify が仕様ファイルを解析し、複数プログラミング言語に対応したコードスニペットの生成や、ブラウザから直接リクエストを送信して挙動を試せる API プレイグラウンド（Playground）を構築します。
設計思想として Docs-as-code（コードとしてのドキュメント）を採用しており、OpenAPI 仕様ファイルは Markdown ドキュメントとともに Git リポジトリでバージョン管理されます。全体の構成は中央設定ファイル（docs.json、旧仕様では mint.json）で定義します。要件に応じて、仕様ファイルから全エンドポイントを自動構築する完全自動化アプローチか、特定の MDX ページにエンドポイントを紐付けて業務背景や前提条件を解説するハイブリッドアプローチのいずれかを選択できます。
前提条件と仕様ファイルの要件
設定を開始する前に、準備した OpenAPI ファイルが以下の要件を満たしているか確認します：
- サポートするバージョン: Mintlify は OpenAPI Specification (OAS) 3.0 および 3.1 をネイティブサポートしています。Swagger 2.0 形式の仕様書を使用している場合は、事前に OpenAPI 3.0 へマイグレーションしてください。
- ファイル形式: JSON（
.json）および YAML（.yamlまたは.yml）の両方に対応しています。 - 参照（$ref）の制約: 単一ファイル内の内部参照（例:
$ref: '#/components/schemas/User'）は正常に解決されますが、別ファイルに分割された外部参照はサポートされていません。スキーマを複数ファイルに分割管理している場合は、Mintlify に取り込む前に Redocly CLI や@apidevtools/swagger-cliなどのツールを用いて単一ファイルへバンドル（統合）してください。
ステップ 1: OpenAPI 仕様ファイルの配置
仕様ファイルは、ローカルリポジトリへの配置またはリモート URL の指定によって参照できます：
-
リポジトリ内への配置（推奨）: ドキュメント用リポジトリ内に仕様ファイルを配置します。一般的には、ルート直下（例:
openapi.json、openapi.yaml）または専用ディレクトリ（例:api-reference/openapi.json、specs/v1.yaml）に配置します。 -
リモート URL の指定: バックエンドの CI/CD パイプラインによって最新の仕様書がオブジェクトストレージや CDN に自動配信されている場合は、HTTPS URL を直接指定できます（例:
https://api.example.com/specs/openapi.json）。本番ビルドでは HTTPS 接続が必須となります。
ステップ 2: docs.json でのナビゲーション設定
左側のサイドバーに API リファレンスを表示するには、docs.json の navigation 配下で仕様ファイルを指定します。
アプローチ A: 全自動リファレンス生成
OpenAPI 仕様書に含まれるすべてのパスを自動解析し、tags に基づいてグループ分けとページ生成を行わせる場合、ナビゲーションタブまたはグループ内でファイル名を直接宣言します：
{
"$schema": "https://mintlify.com/docs.json",
"name": "Acme API Docs",
"navigation": {
"tabs": [
{
"tab": "Guides",
"groups": [
{
"group": "はじめに",
"pages": ["introduction", "quickstart"]
}
]
},
{
"tab": "API Reference",
"openapi": "openapi.json"
}
]
}
}
この設定により、Mintlify は paths 配下のすべてのエンドポイントを走査し、HTTP メソッド、サマリー、詳細説明、パラメータ、レスポンス構造を抽出して、MDX ファイルを 1 つも作成することなく完全な API ドキュメントを構築します。
複数仕様書の管理
マイクロサービスごとに仕様書が分かれている場合や、複数の API バージョンを提供している場合は、配列形式で複数のファイルパスを指定できます：
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": [
"specs/v1/auth.json",
"specs/v1/billing.json",
"specs/v2/core.json"
]
}
]
}
}
ステップ 3: MDX ページによる詳細なカスタマイズ
自動生成は手軽ですが、テクニカルライティングの観点では、特定のエンドポイントに対してビジネスロジックの背景、認証スコープの前提条件、レートリミットの注意喚起、シーケンス図などを併記したいケースが多々あります。Mintlify では MDX のフロントマターを用いて、個別ページと API エンドポイントをバインドできます。
1. MDX ページと特定エンドポイントの連携
MDX ファイル（例: api-reference/users/create.mdx）を作成し、フロントマターの openapi プロパティに HTTP メソッドとパスを記述します：
---
title: "ユーザー作成"
sidebarTitle: "ユーザー作成"
description: "組織内に新しいユーザーアカウントを登録します"
openapi: "POST /v1/users"
---
## 概要
このエンドポイントを呼び出す前に、アクセストークンに `users:write` スコープが付与されていることを確認してください。
<Warning>
ユーザーのメールアドレスは組織内で一意である必要があります。すでに登録されているアドレスを指定すると、`409 Conflict` エラーが返されます。
</Warning>
## Webhook 通知
登録が完了すると、システムは自動的に `user.created` イベントを発行し、設定済みの Webhook エンドポイントへ通知を送信します。
Mintlify は指定された POST /v1/users を仕様書から見つけ出し、対話型リクエストビルダーやパラメータ仕様を自動挿入しつつ、作成した MDX の説明文とシームレスに結合します。
複数の仕様書を読み込んでいる場合は、パスの衝突を避けるためにファイル名を前置します：
---
title: "ユーザー作成"
openapi: "specs/v1/auth.json POST /v1/users"
---
2. Mintlify スクレイパーによる MDX の一括生成
大量のエンドポイントが存在し、それらを個別の MDX ファイルとして一括作成した上で編集したい場合は、公式のスクレイピングツールを活用できます：
npx @mintlify/scraping@latest openapi-file ./openapi.json -o api-reference
このコマンドを実行すると、仕様書を解析して api-reference ディレクトリ配下に各エンドポイント用の MDX ファイルがフロントマター付きで自動生成されます。
ステップ 4: 対話型 API プレイグラウンド（Playground）の構成
ドキュメント閲覧者がその場で実リクエストを送信できるプレイグラウンドを快適に運用するためには、仕様書と設定でいくつかのポイントを押さえる必要があります：
1. ベース URL（接続先サーバー）の定義
Mintlify は OpenAPI 仕様書の servers 配列を読み取ってリクエスト送信先を決定します：
servers:
- url: https://api.example.com/v1
description: 本番環境
- url: https://staging.api.example.com/v1
description: ステージング環境
複数のサーバーが定義されている場合、プレイグラウンド上で接続先を切り替えるドロップダウンが表示されます。
2. 認証方式とテスト用デフォルト値の設定
components.securitySchemes を定義することで、プレイグラウンドに入力フィールド（Bearer トークン、API キー、Basic 認証など）が表示されます：
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: API アクセストークンを入力してください
security:
- bearerAuth: []
ドキュメント読者がすぐに試せるようにサンドボックス用のテストキーを事前に入力しておきたい場合、x-default 拡張プロパティを設定します：
{
"components": {
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"x-default": "demo_pk_live_testing123"
}
}
}
}
3. CORS（Cross-Origin Resource Sharing）への対応
プレイグラウンドからのリクエストは読者のブラウザから直接送信されるため、API サーバー側で適切な CORS 設定が行われている必要があります：
Access-Control-Allow-Origin: *（またはドキュメントサイトのドメイン）Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONSAccess-Control-Allow-Headers: Authorization, Content-Type, X-API-Key
サーバーが OPTIONS プリフライトリクエストを受け入れない場合、curl では成功してもブラウザのプレイグラウンドでは通信エラーとなります。
ステップ 5: OpenAPI Overlays による非破壊的な仕様修正
バックエンドコードから自動生成された仕様書には、社内専用エンドポイントが含まれていたり、説明文が開発者向けで読者に不親切だったりすることがよくあります。仕様書の原本を直接書き換えることなく、ドキュメント公開用に修正を加える仕組みとして、Mintlify は OpenAPI Overlay Specification（v1.1.0） をサポートしています。
オーバーレイファイル（例: overlays/public-filter.yaml）を作成し、JSONPath を用いて update、remove、copy などのアクションを記述します：
overlay: 1.1.0
info:
title: 公開ドキュメント向け調整
version: 1.0.0
extends: ./openapi.json
actions:
- target: $.info.description
update: "Acme 開発者向け公式ドキュメントへようこそ。仕様の確認とオンラインテストが可能です。"
- target: $.paths['/internal/system-health']
remove: true
- target: $.paths['/v1/billing'].post.summary
update: "定期課金サブスクリプションの作成"
このオーバーレイを docs.json に登録します：
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": {
"source": "openapi.json",
"overlays": ["overlays/public-filter.yaml"]
}
}
]
}
}
Mintlify はドキュメントビルド時にオーバーレイを適用し、内部用ルートを除去して文言を改善します。上游のエンジニアリングリポジトリにある原版仕様を汚すことなく、公開用ドキュメントを最適化できます。
ステップ 6: ローカルプレビューと CI/CD 検証
本番環境へ反映する前に、Mintlify CLI を用いてローカルで整合性を確認します：
-
開発サーバーの起動:
npm i -g mintlify mint dev -
ローカル実行中のスキーマサービスのテスト: ローカルで起動中のバックエンドからスキーマを取得している場合（例:
http://localhost:8000/openapi.json）、以下のフラグを付与して起動します：mint dev --local-schema -
厳格なバリデーションチェック: 壊れた参照リンクやスキーマ定義の漏れを検出します：
mint validate -
CI/CD パイプラインへの組み込み: GitHub Actions や GitLab CI に
mint validateを組み込むことで、仕様書のスキーマ破壊や構文エラーをマージ前に検知し、本番ドキュメントの破損を未然に防止できます。