添加 OpenAPI 规范文件
描述你的 API
- Swagger’s OpenAPI Guide:学习 OpenAPI 语法。
- The OpenAPI specification Markdown sources:参考最新版 OpenAPI 规范的详细信息。
- Swagger Editor:用于编辑、验证和调试你的 OpenAPI 文档。
- The Mint CLI:使用以下命令验证你的 OpenAPI 文档:
mint openapi-check <openapiFilenameOrUrl>
。
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
servers
字段,并设置 API 的基础 URL。
/users/{id}
或简写为 /
。基础 URL 用于确定这些路径应当附加到哪里。关于如何配置 servers
字段,请参阅 OpenAPI 文档中的 API Server and Base Path。
API 操作台会使用这些服务器 URL 来确定请求的发送目标。如果你指定了多个服务器,将提供一个下拉菜单,方便用户在服务器之间切换。如果未指定服务器,API 操作台会使用简易模式,因为没有基础 URL 就无法发送请求。
如果你的 API 在不同的 URL 下有端点,你可以针对特定路径或操作覆盖 servers 字段。
指定认证方式
securitySchemes
和 security
字段。API 说明与 API 操作台会基于 OpenAPI 文档中的安全配置自动添加认证字段。
1
Define your authentication method.
添加
securitySchemes
字段以定义用户的认证方式。以下示例展示了 Bearer 认证的配置。2
Apply authentication to your endpoints.
添加
security
字段以要求进行认证。x-mint
扩展
x-mint
是一个自定义的 OpenAPI 扩展,可对 API 文档的生成和展示进行更精细的控制。
Metadata
x-mint: metadata
,即可覆盖生成的 API 页面默认 metadata。除 openapi
外,你可以使用任何在 MDX
frontmatter 中有效的 metadata 字段:
内容
x-mint: content
在自动生成的 API 文档之前添加内容:
content
扩展支持所有 Mintlify 的 MDX 组件和格式。
Href
x-mint: href
更改文档中端点页面的 URL:
x-mint: href
时,导航条目将直接指向指定的 URL,而不会生成 API 页面。
MCP
x-mint: mcp
可选择性地将端点暴露为 Model Context Protocol(MCP)工具。仅启用在通过 AI 工具公开访问时依然安全的端点。
该端点的 MCP 配置。
自动填充 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
属性。
- 专用 API 分区:在导航元素中引用 OpenAPI 规范,作为独立的 API 分区。
- 选择性端点:在导航中与其他页面并列引用特定端点。
专用 API 分区
openapi
字段且不包含其他页面,即可生成专用的 API 分区。规范中的所有端点都会被包含:
directory
字段是可选的,用于指定在你的文档仓库中存放生成的 API 页面的位置。若未指定,则默认为仓库中的 api-reference
目录。选择性端点
设置默认 OpenAPI 规范
pages
字段中引用特定端点:
METHOD /path
格式的页面条目都会使用默认的 OpenAPI 规范为该端点生成一个 API 页面。
OpenAPI 规范继承
单个端点
为 API 页面创建 MDX
文件
MDX
页面。这样可以自定义页面 metadata,添加内容、略过某些操作,或在页面级别于导航中重新排序页面。
参见 MindsDB 的MDX OpenAPI 页面示例及其在在线文档中的呈现方式。
手动指定文件
MDX
页面,并在 frontmatter 中使用 openapi
字段指定要展示的 OpenAPI 操作。
以这种方式引用 OpenAPI 操作时,名称、说明、参数、响应以及 API 操作台会根据你的 OpenAPI 文档自动生成。
如果你有多个 OpenAPI 文件,请在引用中包含文件路径,以确保 Mintlify 能找到正确的 OpenAPI 文档。若只有一个 OpenAPI 文件,Mintlify 将自动检测。
无论你是否在导航中设置了默认 OpenAPI 规范,此方法都适用。
你可以通过在 frontmatter 中包含文件路径,引用任何 OpenAPI
规范中的任意端点。
docs.json
中。
method 和 path 必须与 OpenAPI 规范中的定义完全匹配。
如果该端点在 OpenAPI 文件中不存在,页面将为空。
自动生成 MDX
文件
MDX
页面。
你的 OpenAPI 文档必须有效,否则文件将无法自动生成。
- 针对 OpenAPI 文档中
paths
字段的每个操作生成一个MDX
页面。 - 如果你的 OpenAPI 文档是 3.1+ 版本,则会针对文档中
webhooks
字段的每个操作生成一个MDX
页面。 - 一组可添加到
docs.json
的 navigation 条目数组。
1
生成 `MDX` 文件。
2
指定输出文件夹。
-o
标志以指定输出文件夹。若未指定文件夹,文件将生成在当前工作目录中。为 OpenAPI 模式创建 MDX
文件
components.schema
字段中定义的任意 OpenAPI 模式创建独立页面:
Webhooks
在 OpenAPI 规范中定义 webhooks
paths
字段并列添加 webhooks
字段。
有关定义 webhooks 的更多信息,请参阅 OpenAPI 文档中的 Webhooks。
在 MDX 文件中引用 webhooks
webhook
,而不是 GET
或 POST
等 HTTP 方法:
Webhook 名称必须与 OpenAPI 规范中
webhooks
字段中定义的 key 完全一致。