跳转到主要内容
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 来决定将请求发送到哪里。如果你指定了多个服务器，用户可以通过下拉菜单在服务器之间切换。如果未指定服务器，由于缺少基础 URL 无法发送请求，API交互测试台将使用简易模式。 如果你的 API 在不同的 URL 下有端点，你可以为特定路径或操作覆盖 servers 字段。

​
指定认证

要在 API 文档和交互测试台中启用认证，请在 OpenAPI 文档中配置 securitySchemes 和 security 字段。API 描述和 API交互测试台会根据 OpenAPI 文档中的安全配置自动添加认证字段。
1

Define your authentication method.

添加 securitySchemes 字段以定义用户如何进行认证。以下示例展示了 Bearer 认证的配置。
{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
2

Apply authentication to your endpoints.

添加 security 字段以对端点启用认证要求。
{
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
常见的认证类型包括：
  • API Keys：用于基于 header、query 或 cookie 的密钥。
  • Bearer：用于 JWT 或 OAuth 令牌。
  • Basic：用于用户名和密码。
如果你的 API 中的不同端点需要不同的认证方式，你可以为特定操作覆盖 security 字段。 有关定义和应用认证的更多信息，请参阅 OpenAPI 文档中的Authentication。

​
x-mint 扩展

x-mint 扩展是一个自定义的 OpenAPI规范 扩展，可为 API 文档的生成与展示提供更精细的控制。

​
元数据

在任意 operation 中添加 x-mint: metadata，即可覆盖自动生成的 API 页面默认元数据。你可以使用除 openapi 外的任意在 MDX frontmatter 中有效的元数据字段： 
{
  "paths": {
    "/users": {
      "get": {
        "summary": "获取用户",
        "description": "获取用户列表",
        "x-mint": {
          "metadata": {
            "title": "列出所有用户",
            "description": "获取可筛选的分页用户数据",
            "og:title": "显示用户列表",
          }
        },
        "parameters": [
          {
            // 参数设置
          }
        ]
      }
    }
  }
}

​
内容

使用 x-mint: content 在自动生成的 API 文档之前添加内容： 
{
  "paths": {
    "/users": {
      "post": {
        "summary": "创建用户",
        "x-mint": {
          "content": "## 前置条件\n\n此端点需要管理员权限，并受到速率限制。\n\n<Note>用户邮箱在整个系统内必须唯一。</Note>"
        },
        "parameters": [
          {
            // 参数配置
          }
        ]
      }
    }
  }
}
content 扩展支持所有 Mintlify 的 MDX 组件和格式。

​
Href

使用 x-mint: href 更改文档中端点页面的 URL： 
{
  "paths": {
    "/legacy-endpoint": {
      "get": {
        "summary": "旧版接口",
        "x-mint": {
          "href": "/deprecated-endpoints/legacy-endpoint"
        }
      }
    },
    "/documented-elsewhere": {
      "post": {
        "summary": "特殊接口"
        "x-mint": {
          "href": "/guides/special-endpoint-guide"
        }
      }
    }
  }
}
当存在 x-mint: href 时，导航项将直接链接到指定的 URL，而不会生成 API 页面。

​
MCP

通过使用 x-mint: mcp 有选择地将端点暴露为模型上下文协议（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
        // ...
      }
    }
  }
}
更多信息，请参阅模型上下文协议。

​
自动生成 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 文档",
        "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
    }
  ]
}
你可以在不同的导航部分使用多个 OpenAPI规范： 
"navigation": {
  "tabs": [
    {
      "tab": "API 参考",
      "groups": [
        {
          "group": "用户",
          "openapi": {
            "source": "/path/to/openapi-1.json",
            "directory": "api-reference"
          }
        },
        {
          "group": "管理",
          "openapi": {
            "source": "/path/to/openapi-2.json",
            "directory": "api-reference"
            "directory": "api-reference"
        }
      ]
    }
  ]
}
directory 字段是可选的，用于指定在你的文档仓库中生成的 API 页面存放位置。若未指定，默认为仓库的 api-reference 目录。

​
选择性展示端点

当你希望更精确地控制端点在文档中的出现位置时，可以在导航中引用特定端点。此方式允许你在其他内容旁生成这些 API 端点的页面。

​
设置默认 OpenAPI 规范

为某个导航元素配置默认的 OpenAPI 规范。然后在 pages 字段中引用特定端点： 
"navigation": {
  "tabs": [
    {
      "tab": "快速上手",
      "pages": [
        "quickstart",
        "installation"
      ]
    },
    {
      "tab": "API 参考",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "API 概览",
        "GET /users",
        "POST /users",
        "指南/身份验证"
      ]
    }
  ]
}
任何符合 METHOD /path 格式的页面项都会使用默认的 OpenAPI规范 为该端点生成一个 API 页面。

​
OpenAPI 规范继承

OpenAPI 规范会沿导航层级向下继承。子级导航元素会继承其父级的 OpenAPI 规范，除非它们定义了自己的规范： 
{
  "group": "API参考",
  "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 schema 创建 MDX 文件

你可以为 OpenAPI 文档的 components.schema 字段中定义的任意 OpenAPI schema 创建独立页面： 
---
openapi-schema: OrderItem
---

​
Webhooks

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

​
在 OpenAPI 规范中定义 webhooks

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

​
在 MDX 文件中引用 webhooks

为 webhooks 创建 MDX 页面时，使用 webhook，而不是使用 GET 或 POST 等 HTTP 方法： 
---
title: "Webhook 示例"
description: "在事件发生时触发"
openapi: "path/to/openapi-file webhook example-webhook-name"
---
Webhook 名称必须与 OpenAPI 规范中 webhooks 字段所定义的键完全一致。