OpenAPI は API を記述するための仕様です。Mintlify は OpenAPI 3.0+ をサポートしており、インタラクティブな API ドキュメントを生成し、最新の状態に保てます。

​
OpenAPI 仕様ファイルを追加する

OpenAPI でエンドポイントをドキュメント化するには、OpenAPI Specification 3.0+ に準拠した、有効な JSON または YAML 形式の OpenAPI ドキュメントが必要です。 1 つまたは複数の OpenAPI ドキュメントから API ページを作成できます。

​
API の記述

OpenAPI ドキュメントの学習と作成には、次のリソースをおすすめします。
Swagger の OpenAPI ガイドは OpenAPI v3.0 向けですが、ほぼすべての情報は v3.1 にも適用できます。v3.0 と v3.1 の違いについては、OpenAPI ブログの Migrating from OpenAPI 3.0 to 3.1.0 を参照してください。

​
API の URL を指定する

APIプレイグラウンドなどの Mintlify 機能を有効化するには、OpenAPI ドキュメントに API のベース URL を持つ servers フィールドを追加してください。 
{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}
OpenAPI ドキュメントでは、/users/{id} や / のように各 API エンドポイントはパスで定義されます。ベース URL は、これらのパスをどこに付加するかを示します。servers フィールドの設定方法については、OpenAPI ドキュメントの API Server and Base Path を参照してください。 APIプレイグラウンドは、これらのサーバー URL を使用してリクエストの送信先を判断します。複数のサーバーを指定した場合は、ドロップダウンでサーバーを切り替えられます。サーバーを指定しない場合は、ベース URL がないためリクエストを送信できず、APIプレイグラウンドはシンプルモードで動作します。 API に異なる URL 上に存在するエンドポイントがある場合は、特定のパスまたはオペレーションごとに servers フィールドをオーバーライド できます。

​
認証の指定

API ドキュメントと APIプレイグラウンドで認証を有効にするには、OpenAPI ドキュメントで securitySchemes と security フィールドを設定します。API の説明と APIプレイグラウンドは、OpenAPI ドキュメントのセキュリティ設定に基づいて認証フィールドを追加します。
1

認証方法を定義する

ユーザーの認証方法を定義するために securitySchemes フィールドを追加します。次の例は Bearer 認証の設定です。
{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
2

エンドポイントに認証を適用する

認証を必須にするには security フィールドを追加します。
{
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
一般的な認証タイプには次のものがあります：
  • API Keys: ヘッダー、クエリ、またはクッキーで渡すキー。
  • Bearer: JWT または OAuth トークン。
  • Basic: ユーザー名とパスワード。
API 内でエンドポイントごとに異なる認証方法が必要な場合は、該当のオペレーションに対してsecurity フィールドをオーバーライドできます。 認証の定義と適用の詳細は、OpenAPI ドキュメントの Authentication を参照してください。

​
x-mint 拡張

x-mint は、API ドキュメントの生成と表示をより柔軟に制御できるカスタム OpenAPI 拡張です。

​
メタデータ

生成された API ページのデフォルトメタデータは、任意のオペレーションに x-mint: metadata を追加することで上書きできます。openapi を除き、MDX のフロントマターで有効な任意のメタデータフィールドを使用できます。 
{
  "paths": {
    "/users": {
      "get": {
        "summary": "Get users",
        "description": "Retrieve a list of users",
        "x-mint": {
          "metadata": {
            "title": "List all users",
            "description": "Fetch paginated user data with filtering options",
            "og:title": "Display a list of users"
          }
        },
        "parameters": [
          {
            // Parameter configuration
          }
        ]
      }
    }
  }
}

​
コンテンツ

自動生成される API ドキュメントの前に、x-mint: content を使ってコンテンツを追加します: 
{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create user",
        "x-mint": {
          "content": "## 前提条件\n\nこのエンドポイントには管理者権限が必要で、レート制限が適用されます。\n\n<Note>ユーザーのメールアドレスはシステム全体で一意である必要があります。</Note>"
        },
        "parameters": [
          {
            // Parameter configuration
          }
        ]
      }
    }
  }
}
content 拡張は、Mintlify のすべての MDX コンポーネントと書式をサポートします。

​
Href

x-mint: href を使用して、ドキュメント内のエンドポイントページのURLを変更します。 
{
  "paths": {
    "/legacy-endpoint": {
      "get": {
        "summary": "Legacy endpoint",
        "x-mint": {
          "href": "/deprecated-endpoints/legacy-endpoint"
        }
      }
    },
    "/documented-elsewhere": {
      "post": {
        "summary": "Special endpoint",
        "x-mint": {
          "href": "/guides/special-endpoint-guide"
        }
      }
    }
  }
}
x-mint: href が指定されている場合、ナビゲーションの項目はAPIページを生成せず、指定されたURLへ直接リンクします。

​
MCP

x-mint: mcp を使用して、必要なエンドポイントだけを選択的に Model Context Protocol（MCP）ツールとして公開します。AIツール経由で一般公開しても安全なエンドポイントのみを有効化してください。
​
mcp
object
エンドポイント用の MCP 設定。
{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create user",
        "x-mint": {
          "mcp": {
            "enabled": true
          },
          // ...
        }
      }
    },
    "/users": {
      "delete": {
        "summary": "Delete user (admin only)",
        // No `x-mint: mcp` so this endpoint is not exposed as an MCP tool
        // ...
      }
    }
  }
}
詳細は Model Context Protocol を参照してください。

​
APIページの自動生成

docs.json の任意のナビゲーション要素に openapi フィールドを追加すると、OpenAPI エンドポイントのページを自動生成できます。これらのページをナビゲーション内のどこに表示するかは、専用のAPIセクションとしてまとめることも、他のページと並べて配置することも可能です。 openapi フィールドには、ドキュメントリポジトリ内のファイルパス、またはホストされた OpenAPI ドキュメントのURLを指定できます。 生成されたエンドポイントページには、次のデフォルトのメタデータが設定されます:
  • title: 操作の summary フィールド（存在する場合）。summary がない場合は、HTTPメソッドとエンドポイントからタイトルを生成します。
  • description: 操作の description フィールド（存在する場合）。
  • version: 親のアンカーまたはタブの version 値（存在する場合）。
  • deprecated: 操作の deprecated フィールド。true の場合、サイドナビゲーションおよびエンドポイントページのタイトル横に「非推奨」ラベルが表示されます。
自動生成されたAPIページから特定のエンドポイントを除外するには、OpenAPI仕様の該当する操作に x-hidden プロパティを追加してください。
ドキュメントにエンドポイントページを追加する方法は2つあります:
  1. 専用のAPIセクション: 専用のAPIセクション用に、ナビゲーション要素で OpenAPI 仕様を参照します。
  2. 特定エンドポイントの選択: 他のページと並べて、ナビゲーションで特定のエンドポイントを参照します。

​
専用のAPIセクション

ナビゲーション要素に openapi フィールドだけを追加して、他のページは追加せずに専用のAPIセクションを生成できます。仕様内のすべてのエンドポイントが含まれます: 
"navigation": {
  "tabs": [
    {
        "tab": "API Reference",
        "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
    }
  ]
}
異なるナビゲーションセクションで複数のOpenAPI仕様を使用できます: 
"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Users",
          "openapi": {
            "source": "/path/to/openapi-1.json",
            "directory": "api-reference"
          }
        },
        {
          "group": "Admin",
          "openapi": {
            "source": "/path/to/openapi-2.json",
            "directory": "api-reference"
          }
        }
      ]
    }
  ]
}
directory フィールドは任意で、生成されたAPIページをドキュメントリポジトリ内のどこに保存するかを指定します。指定しない場合、リポジトリの api-reference ディレクトリが既定になります。

​
選択的なエンドポイント

ドキュメント内でエンドポイントの表示場所をより柔軟に制御したい場合は、ナビゲーションで特定のエンドポイントを参照できます。この方法により、他のコンテンツと並んでAPIエンドポイントのページを生成できます。

​
既定の OpenAPI 仕様を設定する

ナビゲーション要素に既定の OpenAPI 仕様を設定します。続いて、pages フィールドで特定のエンドポイントを参照します: 
"navigation": {
  "tabs": [
    {
      "tab": "Getting started",
      "pages": [
        "quickstart",
        "installation"
      ]
    },
    {
      "tab": "API reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "api-overview",
        "GET /users",
        "POST /users",
        "guides/authentication"
      ]
    }
  ]
}
METHOD /path という形式に一致するページエントリは、既定の OpenAPI 仕様を用いてそのエンドポイントの API ページを生成します。

​
OpenAPI仕様の継承

OpenAPI仕様はナビゲーションの階層に従って継承されます。子要素は、独自のOpenAPI仕様を定義しない限り、親の仕様を継承します: 
{
  "group": "API reference",
  "openapi": "/path/to/openapi-v1.json",
  "pages": [
    "overview",
    "authentication",
    "GET /users",
    "POST /users",
    {
      "group": "Orders",
      "openapi": "/path/to/openapi-v2.json",
      "pages": [
        "GET /orders",
        "POST /orders"
      ]
    }
  ]
}

​
個別のエンドポイント

ファイルパスを指定することで、デフォルトの OpenAPI 仕様を設定せずに特定のエンドポイントを参照できます。 
"navigation": {
  "pages": [
    "introduction",
    "user-guides",
    "/path/to/openapi-v1.json POST /users",
    "/path/to/openapi-v2.json GET /orders"
  ]
}
この方法は、異なる仕様から個別のエンドポイントだけが必要な場合や、特定のエンドポイントのみを含めたい場合に便利です。

​
APIページ用の MDX ファイルを作成する

各エンドポイントページを個別に管理するには、各オペレーションごとに MDX ページを作成します。これにより、ページのメタデータのカスタマイズ、コンテンツの追加、特定のオペレーションの除外、ナビゲーション内でのページ単位の並び替えが可能になります。 MindsDB の MDX OpenAPI ページの例と、それが彼らの公開ドキュメントでどのように表示されるかをご確認ください。

​
ファイルを手動で指定する

各エンドポイントごとに MDX ページを作成し、フロントマターの openapi フィールドで表示する OpenAPI のオペレーションを指定します。 この方法で OpenAPI のオペレーションを参照すると、名前、説明、パラメータ、レスポンス、そして APIプレイグラウンドが OpenAPI ドキュメントから自動生成されます。 複数の OpenAPI ファイルがある場合は、参照にファイルパスを含めて、Mintlify が正しい OpenAPI ドキュメントを見つけられるようにしてください。OpenAPI ファイルが 1 つだけの場合は、Mintlify が自動的に検出します。
この方法は、ナビゲーションでデフォルトの OpenAPI 仕様を設定しているかどうかに関係なく機能します。フロントマターにファイルパスを含めれば、任意の OpenAPI 仕様の任意のエンドポイントを参照できます。
外部の OpenAPI ファイルを参照する場合は、ファイルの URL を docs.json に追加してください。 
---
title: "Get users"
description: "Returns all plants from the system that the user has access to"
openapi: "/path/to/openapi-1.json GET /users"
deprecated: true
version: "1.0"
---
メソッドとパスは、OpenAPI 仕様内の定義と完全に一致している必要があります。エンドポイントが OpenAPI ファイルに存在しない場合、そのページは空になります。

​
MDX ファイルを自動生成する

Mintlify のscraperを使って、大規模な OpenAPI ドキュメントから MDX ページを自動生成します。
OpenAPI ドキュメントは有効である必要があります。有効でない場合はファイルを自動生成できません。
scraper は次を生成します:
  • OpenAPI ドキュメントの paths フィールド内の各オペレーションごとの MDX ページ
  • OpenAPI ドキュメントがバージョン 3.1+ の場合、webhooks フィールド内の各オペレーションごとの MDX ページ
  • docs.json に追加できるナビゲーション項目の配列
1

`MDX` ファイルを生成する

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
2

出力フォルダを指定する

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference
-o フラグでファイルの出力先フォルダを指定します。指定しない場合は作業ディレクトリに出力されます。

​
OpenAPI スキーマ用の MDX ファイルを作成する

OpenAPI ドキュメントの components.schemas フィールドで定義された任意の OpenAPI スキーマごとに、個別のページを作成できます： 
---
openapi-schema: OrderItem
---

​
Webhooks

Webhooksは、イベント発生時に外部システムへ通知するためにAPIが送信するHTTPコールバックです。WebhooksはOpenAPI 3.1以降のドキュメントでサポートされています。

​
OpenAPI仕様でwebhookを定義する

OpenAPIドキュメントで、paths フィールドと並列して webhooks フィールドを追加します。 webhook の定義について詳しくは、OpenAPIドキュメントの Webhooks を参照してください。

​
MDXファイルでWebhookを参照する

Webhook向けのMDXページを作成する場合は、GET や POST などのHTTPメソッドではなく、webhook を使用します: 
---
title: "Example webhook"
description: "Triggered when an event occurs"
openapi: "path/to/openapi-file webhook example-webhook-name"
---
Webhook名は、OpenAPI仕様の webhooks フィールドで定義されたキーと完全に一致している必要があります。