OpenAPI 是用于描述 API 的规范。Mintlify 支持 OpenAPI 3.0+ 文档，用于生成交互式 API 文档并保持其始终最新。
要使用 OpenAPI 为你的端点撰写文档，你需要一个符合 OpenAPI 3.0+ 规范 的有效 OpenAPI 规范文件（JSON 或 YAML 格式）。
你可以引用多个 OpenAPI 规范为 API 生成页面。你可以在导航中为每个规范组织章节，或从不同规范中引用特定端点。
Mintlify 仅在单个 OpenAPI 文档内支持用于内部引用 的 $ref。不支持外部引用。
我们推荐以下资源，帮助你学习并编写 OpenAPI 规范。
要启用 API playground，请在 OpenAPI 规范中添加 servers 字段，并填写 API 的基础 URL。
{ "servers" : [ { "url" : "https://api.example.com/v1" } ] } 在 OpenAPI 规范中，不同的 API 端点通过其路径来定义，例如 /users/{id}，或直接使用 /。基础 URL 用于指明这些路径应追加到哪里。有关如何配置 servers 字段的更多信息，请参阅 OpenAPI 文档中的 API Server and Base Path 。
API playground 会使用这些服务器 URL 来确定请求的发送目标。如果你指定了多个服务器，将提供一个下拉菜单，允许用户在不同服务器之间切换。如果未指定服务器，API playground 会使用简易模式，因为在没有基础 URL 的情况下无法发送请求。
如果你的 API 的端点分布在不同的 URL 下，你可以为特定路径或操作覆盖 servers 字段 。
要在 API 文档与操练场中启用身份验证，请在 OpenAPI 规范中配置 securitySchemes 和 security 字段。API 描述与 API 操练场会根据 OpenAPI 规范中的安全配置自动添加身份验证字段。
定义你的身份验证方式。
添加 securitySchemes 字段来定义用户如何进行身份验证。 以下示例展示了 Bearer 身份验证的配置： { "components" : { "securitySchemes" : { "bearerAuth" : { "type" : "http" , "scheme" : "bearer" } } } }
将身份验证应用到你的端点。
添加 security 字段以要求进行身份验证。 { "security" : [ { "bearerAuth" : [] } ] } 常见的身份验证类型包括：
如果你的 API 中不同的端点需要不同的身份验证方式，你可以为某个操作覆盖 security 字段 。
有关定义和应用身份验证的更多信息，请参阅 OpenAPI 文档中的Authentication 。
在 OpenAPI 规范中添加 x-mint 扩展即可自定义端点页面。x-mint 扩展可让你更精细地控制 API 文档的生成与展示。
在任意操作中添加 x-mint: metadata，即可覆盖生成的 API 页面的默认元数据。除 openapi 外，你可以使用 MDX frontmatter 中所有有效的元数据字段。
{ "paths" : { "/users" : { "get" : { "summary" : "获取用户" , "description" : "获取用户列表" , "x-mint" : { "metadata" : { "title" : "列出所有用户" , "description" : "获取分页用户数据及筛选选项" , "og:title" : "显示用户列表" } }, "parameters" : [ { // 参数配置 } ] } } } } 使用 x-mint: content 在自动生成的 API 文档之前添加内容。x-mint: content 扩展支持所有 Mintlify MDX 组件和格式。
{ "paths" : { "/users" : { "post" : { "summary" : "创建用户" , "x-mint" : { "content" : "## 前提条件 \n\n 此端点需要管理员权限,并设有速率限制。 \n\n <Note>用户邮箱在系统内必须唯一。</Note>" }, "parameters" : [ { // 参数配置 } ] } } } } 使用 x-mint: href 更改文档中端点页面的 URL。存在 x-mint: href 时，导航项将直接链接到指定的 URL，而不会生成 API 页面。
{ "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: mcp 有选择性地将端点公开为 Model Context Protocol（MCP）工具。仅启用可通过 AI 工具安全公开访问的端点。
该端点的 MCP 配置。 是否将该端点公开为 MCP 工具。优先于文件级配置。
Selective enablement
Global enablement
{ "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 。
在你的 docs.json 中为任意导航元素添加一个 openapi 字段，可自动生成 OpenAPI 端点页面。你可以控制这些页面在导航结构中的位置，既可作为独立的 API 区块，也可与其他页面并列展示。
openapi 字段可接受你文档仓库中的文件路径，或指向托管 OpenAPI 文档的 URL。生成的端点页面具有以下默认元数据值：
title：若存在，则取该操作的 summary 字段；若没有 summary，则根据 HTTP 方法与端点自动生成标题。description：若存在，则取该操作的 description 字段。version：若存在，则取父级锚点或选项卡中的 version 值。deprecated：取该操作的 deprecated 字段。若为 true，则会在侧边导航和端点页面的端点标题旁显示“已弃用”标签。
若要将特定端点从自动生成的 API 页面中排除，请在 OpenAPI 规范中的该操作上添加 x-hidden 属性。 将端点页面添加到文档中有两种方式：
独立的 API 区块 ：在导航元素中引用 OpenAPI 规范以创建独立的 API 区块。选择性端点 ：在导航中与其他页面并列引用特定端点。
在某个导航元素中仅添加一个 openapi 字段（不包含其他页面），即可生成专用的 API 部分。规范中的所有端点都会被纳入。
"navigation" : { "tabs" : [ { "tab" : "API 参考" , "openapi" : "https://petstore3.swagger.io/api/v3/openapi.json" } ] } 若要在文档的不同部分组织多个 OpenAPI 规范，请在导航层级中将每个规范分配到不同的分组。每个分组都可以引用其各自的 OpenAPI 规范。
"navigation" : { "tabs" : [ { "tab" : "API 参考" , "groups" : [ { "group" : "用户 API" , "openapi" : { "source" : "/path/to/users-openapi.json" , "directory" : "users-api-reference" } }, { "group" : "管理 API" , "openapi" : { "source" : "/path/to/admin-openapi.json" , "directory" : "admin-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 规范，除非它们定义了自己的规范。
{ "group" : "API 参考" , "openapi" : "/path/to/openapi-v1.json" , "pages" : [ "概述" , "身份验证" , "GET /users" , "POST /users" , { "group" : "订单" , "openapi" : "/path/to/openapi-v2.json" , "pages" : [ "GET /orders" , "POST /orders" ] } ] } 通过包含文件路径，可在不设置默认 OpenAPI 规范的情况下引用特定端点。你也可以在同一文档部分中引用来自多个 OpenAPI 规范的端点。
"navigation" : { "pages" : [ "introduction" , "user-guides" , "/path/to/users-openapi.json POST /users" , "/path/to/orders-openapi.json GET /orders" ] } 当你需要从不同规范中选取某些单独的端点、只想包含特定端点，或希望将端点与其他类型的文档一并呈现时，这种方法非常有用。
若需对单个端点页面进行更细粒度的控制，可基于你的 OpenAPI 规范创建 MDX 页面。这样你可以自定义页面元数据与内容，并在导航中对页面重新排序或将其排除，同时仍可使用自动生成的参数与响应。
有两种方式使用独立的 MDX 页面为你的 OpenAPI 规范编写文档：
在前置参数（frontmatter）中使用 openapi 字段为端点编写文档。
在前置参数（frontmatter）中使用 openapi-schema 字段为数据模型编写文档。
为每个端点创建一个页面，并在 frontmatter 中使用 openapi 字段指定要展示的 OpenAPI 操作。
--- 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 规范，请在引用中包含文件路径。外部 OpenAPI URL 可在 docs.json 中引用。
要根据你的 OpenAPI 规范自动生成 MDX 文件，请使用 Mintlify 的 scraper 。
npx @mintlify/scraping@latest openapi-file < path-to-openapi-fil e > -o < folder-nam e > 添加 -o 标志以指定输出文件夹。若未指定文件夹，文件将生成在工作目录中。
在 frontmatter 中使用 openapi-schema 字段，为 OpenAPI 规范的 components.schemas 下定义的每个数据结构各创建一个页面。
--- openapi-schema : OrderItem ---
如果在多个文件中存在同名 schema，请明确指定 OpenAPI 文件：
--- openapi-schema : en-schema.json OrderItem ---
Webhook 是你的 API 在事件发生时用于通知外部系统的 HTTP 回调。OpenAPI 3.1+ 文档支持 Webhook。
在你的 OpenAPI 文档中，与 paths 字段并列添加一个 webhooks 字段。
有关定义 Webhook 的更多信息，请参阅 OpenAPI 文档中的 Webhooks 。
要为某个 Webhook（OpenAPI 3.1+）创建 MDX 页面，请使用 webhook 替代某个 HTTP 方法：
--- title : "订单更新 webhook" description : "当订单更新时触发" openapi : "openapi.json webhook orderUpdated" --- Webhook 名称必须与 OpenAPI 规范中 webhooks 字段中的键完全一致。 
