トラブルシューティング

APIリファレンスでよくある問題

APIページが正しく表示されない場合は、以下のよくある設定ミスを確認してください：

All of my OpenAPI pages are completely blank

この場合、Mintlify が OpenAPI ドキュメントを見つけられないか、ドキュメント自体が無効である可能性が高いです。

ローカルで mint dev を実行すると、これらの問題の一部が明らかになるはずです。

OpenAPI ドキュメントが検証に合格することを確認するには:

1. このバリデータにアクセス
2. 「Validate text」タブに切り替え
3. OpenAPI ドキュメントを貼り付け
4. 「Validate it!」をクリック

下に表示されるテキストボックスの枠が緑色であれば、ドキュメントは検証に合格しています。 これは Mintlify が OpenAPI ドキュメントの検証に使用しているのと同じ検証パッケージなので、ここで 合格する場合は、問題は別の箇所にある可能性が高いです。

なお、Mintlify は OpenAPI 2.0 をサポートしていません。ドキュメントがこの仕様バージョンの場合は、 この問題が起きることがあります。editor.swagger.io（Edit > Convert to OpenAPI 3）でドキュメントを変換できます:

One of my OpenAPI pages is completely blank

これは通常、ページのメタデータにある openapi フィールドの記述ミスが原因です。HTTP メソッドとパスが、OpenAPI ドキュメント内の HTTP メソッドとパスと完全に一致していることを確認してください。

問題が起こる例を示します:

get-user.mdx

---
openapi: "GET /users/{id}/"
---

openapi.yaml

paths:
  "/users/{id}":
    get: ...

openapi フィールド内のパスには末尾のスラッシュがありますが、OpenAPI ドキュメント内のパスにはありません。

もう一つよくある問題は、ファイル名の誤記です。openapi フィールドで特定の OpenAPI ドキュメントを指定している場合は、ファイル名が正しいことを確認してください。例えば、openapi/v1.json と openapi/v2.json の 2 つの OpenAPI ドキュメントがある場合、メタデータは次のようになります:

api-reference/v1/users/get-user.mdx

---
openapi: "v1 GET /users/{id}"
---

Requests from the API Playground don't work

カスタムドメインを設定している場合、リバースプロキシが原因の可能性があります。デフォルトでは、APIプレイグラウンド経由のリクエストは、ドキュメントサイト上の /_mintlify/api/request パスへの POST リクエストから始まります。リバースプロキシが GET リクエストのみを許可する設定になっていると、これらのリクエストはすべて失敗します。解決するには、リバースプロキシで /_mintlify/api/request パスへの POST リクエストを許可してください。

また、リバースプロキシの制約で POST リクエストを受け付けられない場合は、settings documentation に記載のとおり、docs.json の api.playground.proxy 設定で、Mintlify がプロキシを介さずにバックエンドへ直接リクエストを送るよう構成できます。この構成を使用する場合は、リクエストがプロキシ経由ではなくユーザーのブラウザから直接送信されるため、サーバー側で CORS を設定する必要があります。

OpenAPI navigation entries are not generating pages

OpenAPI のナビゲーション設定を使用しているのにページが生成されない場合は、次のよくある原因を確認してください：

1. デフォルトの OpenAPI スペックが未設定: ナビゲーション要素に openapi フィールドが設定されていることを確認してください。

"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "GET /users",
        "POST /users"
      ]
    }
  ]
}

2. OpenAPI スペックの継承: 入れ子のナビゲーションを使用している場合、子グループが正しい OpenAPI スペックを継承しているか、または個別に指定していることを確認してください。

3. 検証エラー: mint openapi-check <path-to-openapi-file> を使用して、OpenAPI ドキュメントが有効か検証してください。

Some OpenAPI operations appear in navigation but others don't

1. 非表示のオペレーション: OpenAPI 仕様で x-hidden: true が設定されたオペレーションは、自動生成のナビゲーションに表示されません。
2. 無効なオペレーション: OpenAPI 仕様で検証エラーのあるオペレーションはスキップされる場合があります。OpenAPI ドキュメントに構文エラーがないか確認してください。
3. 手動 vs 自動の取り込み: OpenAPI 仕様からエンドポイントを参照する場合、ナビゲーションに表示されるのは明示的に参照したオペレーションのみです。他のページが自動的に追加されることはありません。これは、子ナビゲーション要素で参照されているオペレーションも同様です。

Mixed navigation (OpenAPI and MDX pages) not working correctly

OpenAPI のオペレーションと通常のドキュメントページをナビゲーションで併用する場合:

1. ファイルの競合: 同じオペレーションに対して MDX ファイルとナビゲーション項目を同時に持つことはできません。たとえば、get-users.mdx がある場合は、ナビゲーションに "GET /users" を含めないでください。オペレーションと同名のファイルが必要な場合は、エンドポイントに x-mint 拡張を使用し、href が別の場所を指すように設定してください。
2. パス解決: OpenAPI のオペレーションに一致しないナビゲーション項目はファイルパスとして扱われます。MDX ファイルが想定どおりの場所に存在することを確認してください。
3. 大文字小文字の区別: OpenAPI のオペレーションの照合は大文字小文字を区別します。ナビゲーション項目では HTTP メソッドを大文字で記載してください。