跳转到主要内容
OpenAPI 是用于描述 API 的规范。Mintlify 支持 OpenAPI 3.0+ 文档,可生成交互式 API 文档并保持其为最新状态。

添加 OpenAPI 规范文件

要使用 OpenAPI 为你的端点编写文档,你需要一份有效的 OpenAPI 文档,使用 JSON 或 YAML 格式,并遵循 OpenAPI specification 3.0+ 你可以基于一个或多个 OpenAPI 文档创建 API 页面。

描述你的 API

我们推荐以下资源来学习并编写你的 OpenAPI 文档。
Swagger’s OpenAPI Guide 面向 OpenAPI v3.0,但几乎所有信息 都适用于 v3.1。关于 v3.0 与 v3.1 的差异,参见 OpenAPI 博客中的 Migrating from OpenAPI 3.0 to 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 文档和操作台中启用认证,请在 OpenAPI 文档中配置 securitySchemessecurity 字段。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 的 key。
  • Bearer:用于 JWT(JSON Web Token)或 OAuth 令牌。
  • Basic:用于用户名和密码。
如果你的 API 中不同的端点需要不同的认证方式,可以针对特定的操作覆盖 security 字段 有关定义和应用认证的更多信息,请参阅 OpenAPI 文档中的 Authentication

x-mint 扩展

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

Metadata

在任意操作中添加 x-mint: metadata,即可覆盖生成的 API 页面默认 metadata。除 openapi 外,你可以使用任何在 MDX frontmatter 中有效的 metadata 字段:
{
  "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 可选择性地将端点暴露为 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。 生成的端点页面具有以下默认 metadata 值:
  • title:若存在,则取该操作的 summary 字段;否则将根据 HTTP 方法和端点生成标题。
  • description:若存在,则取该操作的 description 字段。
  • version:若存在,则取父级锚点或 Tab 的 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 页面的位置。若未指定,则默认为仓库中的 api-reference 目录。

选择性端点

当你希望更精细地控制端点在文档中的展示位置时,可以在导航中引用特定端点。此方法可让你在其他内容旁边生成这些 API 端点的页面。

设置默认 OpenAPI 规范

为某个导航元素配置默认的 OpenAPI 规范,然后在 pages 字段中引用特定端点:
"navigation": {
  "tabs": [
    {
      "tab": "入门指南",
      "pages": [
        "quickstart",
        "installation"
      ]
    },
    {
      "tab": "API 参考",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "api-overview",
        "GET /users",
        "POST /users",
        "guides/authentication"
      ]
    }
  ]
}
任何符合 METHOD /path 格式的页面条目都会使用默认的 OpenAPI 规范为该端点生成一个 API 页面。

OpenAPI 规范继承

OpenAPI 规范会沿着导航层级向下继承。子级导航元素会继承其父级的 OpenAPI 规范,除非它们定义了自己的规范:
{
  "group": "API 参考",
  "openapi": "/path/to/openapi-v1.json",
  "pages": [
    "overview",
    "authentication",
    "GET /users",
    "POST /users",
    {
      "group": "订单",
      "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 页面。这样可以自定义页面 metadata,添加内容、略过某些操作,或在页面级别于导航中重新排序页面。 参见 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: "返回用户可访问的系统中所有植物"
openapi: "/path/to/openapi-1.json GET /users"
deprecated: true
version: "1.0"
---
method 和 path 必须与 OpenAPI 规范中的定义完全匹配。 如果该端点在 OpenAPI 文件中不存在,页面将为空。

自动生成 MDX 文件

使用我们的 Mintlify scraper 为大型 OpenAPI 文档自动生成 MDX 页面。
你的 OpenAPI 文档必须有效,否则文件将无法自动生成。
该 scraper 会生成:
  • 针对 OpenAPI 文档中 paths 字段的每个操作生成一个 MDX 页面。
  • 如果你的 OpenAPI 文档是 3.1+ 版本,则会针对文档中 webhooks 字段的每个操作生成一个 MDX 页面。
  • 一组可添加到 docs.json 的 navigation 条目数组。
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

Webhooks 是当事件发生时,你的 API 用于通知外部系统的 HTTP 回调。OpenAPI 3.1 及以上版本的文档支持 Webhooks。

在 OpenAPI 规范中定义 webhooks

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

在 MDX 文件中引用 webhooks

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