OpenAPI 是用于描述 API 的规范。Mintlify 支持 OpenAPI 3.0+ 文档，可生成交互式 API 文档并保持其及时更新。

​
添加 OpenAPI 规范文件

要使用 OpenAPI 为你的端点编写文档，你需要一份有效的 OpenAPI 文档（JSON 或 YAML 格式），并符合 OpenAPI 3.0+ 规范。 你可以基于单个或多个 OpenAPI 文档创建 API 页面。

​
描述你的 API

我们推荐以下资源来学习并编写你的 OpenAPI 文档。
Swagger 的 OpenAPI 指南面向 OpenAPI v3.0，但其中几乎所有信息 同样适用于 v3.1。关于 v3.0 与 v3.1 的差异，请参阅 OpenAPI 博客中的 从 OpenAPI 3.0 迁移到 3.1.0。

​
为你的 API 指定 URL

要启用 Mintlify 的功能（例如 API 操作台），请在 OpenAPI 文档中添加 servers 字段，并填写 API 的基础 URL。 
{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}
在 OpenAPI 文档中，不同的 API 端点通过其路径来定义，例如 /users/{id} 或简写为 /。基础 URL 决定这些路径应当附加到哪里。有关如何配置 servers 字段的更多信息，请参阅 OpenAPI 文档中的 API Server and Base Path。 API 操作台会使用这些服务器 URL 来确定请求的发送目标。如果你指定了多个服务器，会出现一个下拉菜单，允许用户在不同服务器之间切换。如果未指定服务器，API 操作台将使用简易模式，因为没有基础 URL 时无法发送请求。 如果你的 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: 适用于基于 header、query 或 cookie 的密钥。
  • Bearer: 适用于 JWT 或 OAuth 令牌。
  • Basic: 适用于用户名和密码。
如果 API 中不同端点需要不同的身份验证方式，可以为特定操作覆盖 security 字段。 有关定义与应用身份验证的更多信息，请参阅 OpenAPI 文档中的Authentication。

​
x-mint 扩展

x-mint 是一个自定义的 OpenAPI 扩展，用于对 API 文档的生成和展示方式进行更精细的控制。

​
元数据

在任意操作中添加 x-mint: metadata，即可覆盖生成的 API 页面的默认元数据。除 openapi 外，你可以使用在 MDX frontmatter 中有效的任意元数据字段： 
{
  "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": [
          {
            // 参数配置
          }
        ]
      }
    }
  }
}
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 时，导航项将直接链接到指定的 URL，而不会生成 API 页面。

​
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 属性。
将端点页面添加到文档中有两种方式：
  1. 独立的 API 分区：在导航元素中引用 OpenAPI 规范以构建专用的 API 分区。
  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 页面，并在 frontmatter 中使用 openapi 字段指定要展示的 OpenAPI 操作。 当你以这种方式引用 OpenAPI 操作时，名称、描述、参数、响应，以及 API 操作台都会根据你的 OpenAPI 文档自动生成。 如果你有多个 OpenAPI 文件，请在引用中包含文件路径，以确保 Mintlify 能找到正确的 OpenAPI 文档。若只有一个 OpenAPI 文件，Mintlify 会自动检测。
无论你是否在导航中设置了默认的 OpenAPI 规范，此方法都适用。你可以通过在 frontmatter 中包含文件路径，从任意 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.schema 字段定义的任意 OpenAPI 架构创建独立页面： 
---
openapi-schema: OrderItem
---

​
Webhooks

Webhook 是您的 API 在事件发生时发送的 HTTP 回调，用于通知外部系统。Webhook 在 OpenAPI 3.1+ 文档中受支持。

​
在 OpenAPI 规范中定义 webhook

在 OpenAPI 文档中添加一个与 paths 字段并列的 webhooks 字段。 有关定义 webhook 的更多信息，请参阅 OpenAPI 文档中的 Webhooks。

​
在 MDX 文件中引用 webhook

为 webhook 创建 MDX 页面时，请使用 webhook，而不要使用 GET 或 POST 等 HTTP 方法： 
---
title: "Example webhook"
description: "Triggered when an event occurs"
openapi: "path/to/openapi-file webhook example-webhook-name"
---
webhook 名称必须与 OpenAPI 规范中 webhooks 字段中的键完全一致。