Mintlifyとは：docs.jsonとOpenAPIでAPIドキュメントを公開する手順と料金・注意点

Mintlifyは、Gitリポジトリに置いたMDXの原稿とdocs.jsonという設定ファイルから、開発者向けのドキュメントサイトを生成してホスティングまで引き受けるサービスです。OpenAPIの仕様書を読み込ませると、APIリファレンスとブラウザから試せるプレイグラウンドを自動で作ります。この記事では、Mintlifyの仕組みとmint CLIでのローカル起動、docs.jsonとOpenAPIの書き方、GitHub連携とCIでの検査、料金プラン、Docusaurusとの選び分け、過去のセキュリティ事案から考える配置ドメインの判断までを、公式ドキュメントをもとに実装目線で整理します。CLIの版番号はnpm registryで2026年10月21日に確認した値です。

まとめ：MintlifyでAPIドキュメントを公開してよい条件と避ける場面

結論から書きます。外部の開発者に公開するAPIがあり、OpenAPIの仕様書を既に持っている。この条件がそろうなら、Mintlifyは構築の手間がもっとも小さい選択肢です。仕様書のパスをdocs.jsonに1行書くだけでエンドポイントごとのページができ、プレビュー環境とAIアシスタントも有料プランに含まれます。

反対に、社内向けの手順書を数十ページ置くだけなら、Proプランの月額450ドル（年払い時）は割に合いません。オープンソースのDocusaurusやMkDocsで足ります。もう1つの判断材料はドメインです。Mintlifyは2024年3月にGitHubトークン91件の漏えい、2025年11月に5件のCVEが付いた脆弱性を公表しました。ログイン用のCookieを持つ自社サービスと同じドメイン配下にドキュメントを置く設計は避け、別のサブドメインで運用するのが安全側の選択です。

Mintlifyの仕組み：MDXとdocs.jsonから文書サイトを生成するSaaS

まず、Mintlifyが何を引き受け、何を利用者側に残しているのかを押さえます。

Gitリポジトリ同期・MDX原稿・docs.jsonの3つで成り立つ基本構造

Mintlifyでは、原稿をMDX（Markdownの中にJSXを書ける形式）で書き、サイト名や配色、左メニューの構成をdocs.jsonに記述します。この2種類のファイルをGitHubのリポジトリに置き、Mintlify側のGitHub Appがコミットを検知してビルドと公開を行います。静的サイト生成ツールと違い、ビルドの実行環境もホスティングもMintlifyが持つため、利用者がサーバーやCDNを用意する工程はありません。

公式の雛形はGitHubのmintlify/starterで公開されています。ルートにdocs.json、index.mdx、quickstart.mdxが並ぶ最小構成で、ライセンスはMITです。

OpenAPI 3.0〜3.2からAPIリファレンスとプレイグラウンドを作る機能

Mintlifyを選ぶ理由の大半はここにあります。公式のOpenAPI設定ページによると、対応する仕様書はOpenAPI 3.0・3.1・3.2です。仕様書のsummaryがページのタイトル、descriptionが説明文になり、各ページには実際にリクエストを送れるプレイグラウンドが付きます。

仕様書の指定方法は、リポジトリ内のファイルパスと公開URLのどちらにも対応する形式です。ただし$refは同じファイル内の参照にしか対応しておらず、別ファイルに分けたスキーマは事前に1ファイルへまとめておく必要があります。仕様書そのものの書き方はOpenAPIの仕様書の書き方と3.0・3.1・3.2の差分で解説しています。

llms.txtと.md出力でAIエージェントに文書を渡す仕組み

公式のllms.txtページによると、Mintlifyはサイトのルートにllms.txtとllms-full.txtを自動で配置します。前者は全ページの一覧、後者は全ページの本文をMarkdownで1ファイルにまとめたものです。各ページのURLに.mdを付けるとMarkdown版が返るため、コーディング支援AIに自社APIの仕様を読ませる用途にそのまま使えます。

人が書いて置いたllms.txtがあれば、そちらが優先されます。llms.txtという取り決め自体の位置づけや、検索順位への効果に関するGoogleの見解はllms.txtの書き方と設置方法にまとめました。

mint CLIの導入からdocs.json・OpenAPI設定までのローカル手順

ここからは手を動かす部分です。npm registryで確認したCLIパッケージmintの最新版は4.2.1085（2026年10月21日公開）でした。更新の頻度が高いため、作業前にmint updateで上げておきます。

Node.js 20.17以上でmint CLI導入とmint devの3000番起動

公式のCLI導入ページは、Node.js 20.17.0以上（LTS推奨）を要件にしています。パッケージ側のenginesはnode >=18.0.0のままですが、公式の要件に合わせておくのが無難です。

# CLIを入れる（旧名の mintlify パッケージはCIやインストール用スクリプトで使わない）
npm i -g mint
mint --version

# 雛形を作ってローカルで確認する（http://localhost:3000）
mint new my-docs
cd my-docs
mint dev

# ポートを変える場合
mint dev --port 3333

注意点は1つです。公式の導入ページは、旧パッケージ名のmintlifyをCIやインストール用スクリプトに書かないよう明記したものです。古い手順書を写すと旧名のまま残りやすいため、CI設定はmintで統一します。ページが404になるときは、docs.jsonがあるディレクトリでmint devを実行しているかを先に確かめます。

docs.jsonの必須4項目とタブ・グループでメニューを組む記述例

公式のGlobal settingsページが必須とする項目は、name、theme、colors.primary、navigationの4つだけです。$schemaを書いておくと、対応エディタで補完と検証が効きます。次の例は、ガイドとAPIリファレンスをタブで分けた構成です。

{
  "$schema": "https://mintlify.com/docs.json",
  "name": "Example API",
  "theme": "mint",
  "colors": { "primary": "#0D6EFD" },
  "navigation": {
    "tabs": [
      {
        "tab": "ガイド",
        "groups": [
          { "group": "はじめに", "pages": ["index", "quickstart"] }
        ]
      },
      {
        "tab": "API Reference",
        "openapi": "openapi.json"
      }
    ]
  }
}

pagesに記述するのは、拡張子を除いたページの相対パスです。themeに指定できる値は、公式のThemesページでmint、maple、palm、willow、linden、almond、aspen、sequoia、lumaの9種類が案内されています。旧形式のmint.jsonを使っているリポジトリでは、CLIを更新してmint devを実行するとdocs.jsonが生成されます。中身を確認してからmint.jsonを消す順番です。

タブにopenapiを指定してエンドポイント別ページを自動生成する

上の例の2つ目のタブのように、openapiに仕様書を指定してpagesを省くと、仕様書の全エンドポイントがページになります。特定のエンドポイントだけを自分で書いたMDXにしたい場合は、フロントマターで仕様書とメソッドとパスを1つの文字列で指定します。

---
title: "ユーザー一覧の取得"
openapi: "openapi.json GET /users"
---

一覧は作成日の新しい順で返ります。100件を超える場合は cursor で続きを取得します。

仕様書が複数あるときは、ファイルパスを省略しないことが公式の注意事項です。省略した場合に使われるのは、ファイル名の順で最初に一致した仕様書です。公開したくないエンドポイントは、仕様書の該当操作にx-hiddenを付けると自動生成から外れます。仕様書をURLで読み込む構成では、仕様書を更新してもリポジトリへのpushが起きないため、CIから再デプロイを呼ぶ仕組みが別に要ります。

GitHub連携とCIで公開前にリンク切れ・ビルドエラーを止める運用

Mintlifyはデフォルトブランチへのpushで本番に自動公開されます。便利な反面、壊れた設定もそのまま公開されるため、マージ前に止める仕組みを組んでおきます。

GitHub Appが求める5つの権限と対象リポジトリを絞る設定

公式のGitHub連携ページによると、Mintlifyが使うGitHub Appの権限は、読み取りのみのmetadataと、読み書きのchecks・code・deployments・pull requestsです。書き込み権限は、PRへのステータス表示、プレビューの生成、Webエディタからのブランチ作成に使われます。

インストール時に選ぶ対象は、「Only select repositories」で指定したドキュメント用のリポジトリだけです。製品コードと同じモノレポに原稿を置く場合はサブディレクトリを指定できますが、その場合はアプリの権限が製品コードにも及ぶ点を承知しておく必要があります。GitHub Enterprise CloudでIP許可リストを有効にしている組織では、Mintlifyの送信元IPアドレス54.242.90.151の追加が要ります。

GitHub ActionsのPR時にmint validateとリンク検査を回す設定

公式のCLIコマンド一覧には、ビルドを厳格モードで検証するmint validateと、内部リンク切れを調べるmint broken-linksがあります。mint validateは警告やエラーがあると失敗の終了コードを返すので、その終了コードをそのままCIの合否判定に使うことが可能です。旧来のopenapi-checkは非推奨になり、mint validateへの置き換えが案内されています。

# .github/workflows/docs-check.yml
name: docs-check
on:
  pull_request:
    paths: ["docs/**"]
jobs:
  check:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: docs
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm i -g mint
      - run: mint validate
      - run: mint broken-links --check-anchors --check-redirects

--check-externalを足すと外部URLも調べますが、相手先の一時的な障害でCIが落ちるため、日次の定期実行に分けるほうが運用は安定します。CIの組み方そのものはGitHub Actionsでビルドと自動テストを設定する方法を参照してください。

Mintlifyの料金プランと編集者数・AIアシスタントで変わる費用

料金は公式の料金ページで2026年10月21日に確認した内容です。ドル建てで、改定されることがあるため契約前に再確認してください。

Starter・Pro・Enterpriseの月額と機能差（2026年10月時点）

Proを月払いにすると540ドルです。AIアシスタントは回答1回につき25クレジットを消費し、回答できなかった場合は消費しません。見落としやすいのはSSOで、社内の認証基盤とつなぎたい場合はEnterpriseしか選べません。

無料のStarterで足りる規模とProへ上げる判断の分かれ目

原稿を書く人が5人以内で、PRごとのプレビューが無くても困らないなら、Starterのままで公開まで進められます。ProのPRプレビューが効いてくるのは、開発者以外のレビュアーが画面で原稿を確認する体制のときです。

年払いを選択した場合のProの費用は、年額5,400ドルです。この金額は、オープンソースのツールで組んだサイトの保守を外部に頼む費用と比べて判断します。ビルド環境やホスティングの保守を自社で持てるチームなら、Proの価値はAIアシスタントと閲覧分析にほぼ絞られます。

Docusaurusとの比較で決めるMintlifyの採用条件と見送る場面

同じ用途でよく比べられるのが、Meta製のオープンソースであるDocusaurusです。

ホスティング・OpenAPI対応・費用で見るDocusaurusとの違い

差がもっとも大きいのは、配信基盤を誰が持つかです。Mintlifyは配信を引き受ける代わりに、サイトのデータと公開の可否を事業者に預けます。手元に持ち出せるのはmint exportで作るオフライン閲覧用のzipで、そのまま別の基盤へ移せる形ではありません。Docusaurusの構築手順と多版・多言語の設定はDocusaurusの構築手順とバージョン管理・多言語の設定で扱っています。

MintlifyをAPI公開に採用する2条件と見送るべき4つの場面

採用してよいのは、次の2つを同時に満たす場合です。1つは、外部の開発者に向けてAPIを公開していて、OpenAPIの仕様書を開発の過程で保守していること。もう1つは、ドキュメントのビルドと配信を自社で保守する人員を置けないことです。

次のどれかに当たるなら見送ります。

• データを国内や自社管理の環境に置く契約上の義務がある
• 社内向けの手順書だけで、公開APIが無い
• ログイン状態を持つ自社サービスと同じドメインのパス配下に置く必要がある
• 仕様書が無く、APIの設計そのものが固まっていない

最後の場面は、ツールを替えても解決しません。仕様書の項目をどこまで書くかはAPI仕様書の記載項目チェックリストで確認できます。APIの設計や外部システムとの連携から相談したい場合は、当社のAPI開発・システム連携で、仕様書の整備を含めて引き受けています。

過去2件のセキュリティ事案から決めるドキュメントの配置ドメイン

ホスト型を選ぶなら、事業者側で起きた事案も判断材料に入れます。どちらも公式に報告されたものです。

2024年3月のGitHubトークン91件漏えいと2025年11月の5件のCVE

1件目は、2024年3月13日付の公式インシデント報告です。3月1日に不審なアクセスを検知し、内部の管理者用トークンが脆弱性経由で漏れていたことが判明しました。保存していた顧客のGitHubトークン91件が漏えいし、1社のリポジトリへのアクセスが確認されています。同社は全トークンを失効させています。

2件目は、2025年11月のセキュリティ事案の報告です。静的ファイルの配信経路で顧客ごとの分離が不十分で、ある顧客がアップロードしたSVGを別の顧客のドメイン上で実行させられる状態でした。MDXのサーバー側描画でのコード実行なども見つかり、公式のステータスページではCVE-2025-67842〜67846の5件として記録されています。いずれも数時間以内に修正され、悪用の形跡は見つからなかったとしています。

docsを本体ドメイン配下に置く前に確かめるCookieのスコープ

2025年11月の報告で、同社は影響が大きくなる条件を挙げています。example.com/docsのように自社サービスと同じドメインに置き、認証用のCookieやlocalStorageを共有している構成と、ワイルドカードドメインのCookieを使っている構成です。逆に、別ドメインやスコープを絞ったCookie、既定の*.mintlify.appで運用している場合はリスクが低いとしています。

実務では、ドキュメントはdocs.example.comのような別のサブドメインに置き、本体サービスの認証CookieはDomain属性を付けずにホスト限定にします。ドキュメント上で外部のスクリプトが動いた場合に何が起きるかは、XSSとCSRFの違いと実装レベルの対策で仕組みから確認できます。

よくある質問

Mintlifyの導入検討でよく挙がる論点を、公式ドキュメントと料金ページの記載をもとに整理します。

Mintlifyは無料で使えますか？

使えます。料金ページのStarterプランは月額0ドルで、編集者5人まで、独自ドメインも設定できます。AIアシスタント、PRごとのプレビュー、SSOは含まれません。これらが必要になった段階でProかEnterpriseを検討します。料金はドル建てで改定されることがあるため、契約前に公式の料金ページを確認してください。

Mintlifyで日本語のドキュメントは作れますか？

日本語のドキュメントも問題なく作成できます。原稿はMDXなので本文は日本語で書けますし、docs.jsonのタブ名やグループ名にも日本語を記述できる仕様です。英語版と並べる場合は、公式のNavigationページにあるnavigation.languagesで言語ごとにメニューを組む構成です。日本語の言語コードはjaではなくjpと定められている点に注意が要ります。ページもjp/quickstartのように言語別のパスで参照します。

MintlifyのサイトをGitHub以外のGitサービスで管理できますか？

GitLabであれば、原稿を管理する連携先として選択可能です。公式のGitLab連携ページによると、プロジェクトアクセストークン（ロールはMaintainer、スコープはapiとread_api）とWebhookで同期します。セルフホストのGitLabも対象ですが、インスタンスがMintlifyから到達できる場所に公開され、443番のHTTPSで応答する必要があります。社内ネットワークに閉じたGitサーバーでしか原稿を管理できない組織には向きません。

Mintlifyから別のツールへ移行できますか？

原稿はMDX、設定はdocs.jsonとしてリポジトリに残るため、文章そのものは持ち出せます。手間がかかるのは、Mintlify独自のコンポーネントを使った箇所と、OpenAPIから自動生成していたAPIリファレンスです。移行先で同じ表示を作り直す作業が発生します。独自コンポーネントの使用箇所を絞っておくと、移行時の書き換えが減ります。

mint.jsonとdocs.jsonの違いは何ですか？

mint.jsonは旧形式の設定ファイルで、現在の設定ファイルはdocs.jsonです。CLIをmint updateで更新してからmint devを実行すると、既存のmint.jsonからdocs.jsonが生成されます。生成内容を確認し、ローカルで表示が崩れていないことを確かめてからmint.jsonを削除します。

関連記事

• Docusaurusとは：ドキュメントサイトの構築手順とバージョン管理・多言語・検索の設定【3.10対応】
• OpenAPIとは？Swaggerとの違いと仕様書(YAML/JSON)の書き方｜3.0・3.1・3.2の差分
• API仕様書・設計書の書き方｜記載項目チェックリストとOpenAPIサンプル・テンプレート
• llms.txtとは？書き方・設置方法とv2の変更点、Googleが効果なしとする理由【2026年9月】
• ドキュメント化とは？エンジニアが書かない理由と開発現場で回る仕組み