---
title: "Mintlifyとは：docs.jsonとOpenAPIでAPIドキュメントを公開する手順と料金・注意点"
url: "https://www.issoh.co.jp/tech/details/18709/"
published: 2026-10-21
updated: 2026-10-21
categories: ["開発"]
publisher: "株式会社一創"
---

# 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](https://github.com/mintlify/starter)で公開されています。ルートに`docs.json`、`index.mdx`、`quickstart.mdx`が並ぶ最小構成で、ライセンスはMITです。

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

Mintlifyを選ぶ理由の大半はここにあります。[公式のOpenAPI設定ページ](https://www.mintlify.com/docs/api-playground/openapi-setup)によると、対応する仕様書はOpenAPI 3.0・3.1・3.2です。仕様書の`summary`がページのタイトル、`description`が説明文になり、各ページには実際にリクエストを送れるプレイグラウンドが付きます。

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

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

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

人が書いて置いた`llms.txt`があれば、そちらが優先されます。`llms.txt`という取り決め自体の位置づけや、検索順位への効果に関するGoogleの見解は[llms.txtの書き方と設置方法](https://www.issoh.co.jp/column/details/6984/)にまとめました。

## 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導入ページ](https://www.mintlify.com/docs/cli/install)は、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ページ](https://www.mintlify.com/docs/organize/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ページ](https://www.mintlify.com/docs/customize/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連携ページ](https://www.mintlify.com/docs/deploy/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コマンド一覧](https://www.mintlify.com/docs/cli/commands)には、ビルドを厳格モードで検証する`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でビルドと自動テストを設定する方法](https://www.issoh.co.jp/tech/details/2497/)を参照してください。

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

料金は[公式の料金ページ](https://www.mintlify.com/pricing)で2026年10月21日に確認した内容です。ドル建てで、改定されることがあるため契約前に再確認してください。

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

| プラン        | 月額         | 編集者 | 主な差            |
| ---------- | ---------- | --- | -------------- |
| Starter    | 0ドル        | 5人  | 独自ドメイン可        |
| Pro        | 450ドル（年払い） | 無制限 | AIアシスタント・プレビュー |
| Enterprise | 個別見積もり     | 無制限 | SSO・SCIM・RBAC  |

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    | Docusaurus  |
| --------- | ----------- | ----------- |
| 提供形態      | ホスト型SaaS    | OSS（MIT）    |
| 公開先       | Mintlifyが配信 | 任意の静的ホスティング |
| APIリファレンス | 標準で生成       | プラグインを追加    |
| 版の出し分け    | 設定で対応       | 標準コマンドで対応   |
| 費用        | Proは月450ドル〜 | ツール自体は無料    |

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

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

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

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

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

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

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

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

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

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

2件目は、[2025年11月のセキュリティ事案の報告](https://www.mintlify.com/blog/working-with-security-researchers-november-2025)です。静的ファイルの配信経路で顧客ごとの分離が不十分で、ある顧客がアップロードしたSVGを別の顧客のドメイン上で実行させられる状態でした。MDXのサーバー側描画でのコード実行なども見つかり、[公式のステータスページ](https://status.mintlify.com/incidents/01KCSDH01X5D4AK4YDJ8J1CH2D)では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の違いと実装レベルの対策](https://www.issoh.co.jp/tech/details/4109/)で仕組みから確認できます。

## よくある質問

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

### Mintlifyは無料で使えますか？

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

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

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

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

GitLabであれば、原稿を管理する連携先として選択可能です。[公式のGitLab連携ページ](https://www.mintlify.com/docs/deploy/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対応】](https://www.issoh.co.jp/tech/details/18707/)
- [OpenAPIとは？Swaggerとの違いと仕様書(YAML/JSON)の書き方｜3.0・3.1・3.2の差分](https://www.issoh.co.jp/tech/details/10408/)
- [API仕様書・設計書の書き方｜記載項目チェックリストとOpenAPIサンプル・テンプレート](https://www.issoh.co.jp/tech/details/4068/)
- [llms.txtとは？書き方・設置方法とv2の変更点、Googleが効果なしとする理由【2026年9月】](https://www.issoh.co.jp/column/details/6984/)
- [ドキュメント化とは？エンジニアが書かない理由と開発現場で回る仕組み](https://www.issoh.co.jp/column/details/2578/)

---

出典: [Mintlifyとは：docs.jsonとOpenAPIでAPIドキュメントを公開する手順と料金・注意点](<https://www.issoh.co.jp/tech/details/18709/>)（株式会社一創）