OpenAPI 是用于描述 API 的规范。Mintlify 支持 OpenAPI 3.0 和 3.1 文档，用于生成交互式 API 文档并保持其始终最新。
要使用 OpenAPI 为你的端点撰写文档，你需要一个或多个有效的 OpenAPI 规范文件，格式为 JSON 或 YAML，并且遵循 OpenAPI 3.0 或 3.1 规范 。
将 OpenAPI 规范添加到你的文档存储库中，或将其托管在线，以便你可以通过 URL 访问这些规范。存储在存储库中的规范会在你的文档域名上按照其路径提供为可下载文件 。例如，https://your-domain/docs/openapi.json。
在 docs.json 的 navigation 配置中引用任意数量的 OpenAPI 规范，以为你的 API 端点创建页面。每个规范文件都会生成自己的一组端点。
Single specification
Multiple specifications
"navigation" : { "tabs" : [ { "tab" : "API Reference" , "openapi" : "openapi.json" } ] }
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 。
在安全方案上使用 x-default 扩展，可以在 API playground 中预填身份验证字段。这对于提供占位值或测试凭据非常有用，能帮助用户快速上手。
{ "components" : { "securitySchemes" : { "apiKey" : { "type" : "apiKey" , "in" : "header" , "name" : "X-API-Key" , "x-default" : "your-api-key-here" } } } } x-default 扩展支持 apiKey 和 http bearer 安全方案类型。该值会作为 playground 身份验证字段中的默认输入显示。你还可以在 OpenAPI 规范中的任何 schema 属性上使用 x-default，以在 API playground 中设置默认值，而不影响 schema 定义中的 default 字段。
在 OpenAPI 规范中添加 x-mint 扩展即可自定义端点页面。x-mint 扩展可让你进一步控制 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" : "获取分页用户数据及筛选选项" , "og:title" : "Display a list of users" } }, "parameters" : [ { // Parameter configuration } ] } } } } 你还可以使用 playground 和 groups metadata 字段，为每个 endpoint 单独控制 playground 的展示：
{ "paths" : { "/admin/users" : { "post" : { "summary" : "创建管理员用户" , "x-mint" : { "metadata" : { "playground" : "auth" , "groups" : [ "admin" ], "public" : true } } } } } } 此配置会让页面对所有人可见，但只有属于 admin 组的已认证用户才能使用交互式 Playground。
使用 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 时，生成的 API 页面将使用指定的 URL，而不是默认自动生成的 URL。
{ "paths" : { "/legacy-endpoint" : { "get" : { "summary" : "旧版端点" , "x-mint" : { "href" : "/deprecated-endpoints/legacy-endpoint" } } }, "/documented-elsewhere" : { "post" : { "summary" : "特殊端点" , "x-mint" : { "href" : "/guides/special-endpoint-guide" } } } } } 在你的 docs.json 中为任意导航元素添加一个 openapi 字段，可自动生成 OpenAPI 端点页面。你可以控制这些页面在导航结构中的位置，既可作为独立的 API 区块，也可与其他页面并列展示。
openapi 字段可接受你文档仓库中的路径，或指向托管 OpenAPI 文档的 URL。当你使用 URL 指定 OpenAPI 规范时，规范的更改不会触发 Git 推送，因此你的文档不会自动重新部署。为了保持文档同步，请在生成或更新规范的同一个 CI 操作中调用 Trigger deployment API 端点。这样你的文档就会自动更新，无需从仪表板手动触发部署。 生成的端点页面具有以下默认元数据值：
title：若存在，则取该操作的 summary 字段；若没有 summary，Mintlify 会根据 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 字段为可选项，用于指定 Mintlify 将生成的 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 规范，除非它们定义了自己的规范。
{ "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 规范，请在引用中包含对应规范文件的路径。您也可以在 docs.json 中引用外部 OpenAPI URL。
要根据你的 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 字段中的键完全一致。 
