docs.json 中的任意导航元素(例如标签页、锚点或分组)上添加 openapi 字段,即可从规范生成端点页面。openapi 字段接受文档仓库中的路径或托管规范的 URL。
你可以通过两种方式添加端点:
- 从整个规范生成一个部分。 每个端点都会获得一个页面,并按 tag 分组。大多数 API 参考都适合使用这种方式。
- 列出特定端点。 只有你列出的端点会获得页面,按你列出的顺序排列,并与其他页面放在一起。
pages 的导航元素上添加 openapi 字段。规范中的每个端点都会在该元素中获得一个页面。
docs.json
name。要显示不同的标签,请为该 tag 添加 x-group。URL 仍使用 tag 的 name。
x-group,Mintlify 会使用其 x-displayName 扩展作为标签,因此已经使用 x-displayName 的规范无需修改。如果某个 tag 同时具有两者,以 x-group 为准。
在 OpenAPI 3.2 文档中,tag 可以声明 parent、kind 和 summary 字段。Mintlify 会使用它们构建嵌套分组。OpenAPI 3.0 和 3.1 文档则为每个 tag 保留一个扁平分组。
parent:将该 tag 的分组嵌套在父 tag 的分组中。summary:设置分组标签。如果 tag 还具有x-group或x-displayName,以扩展为准,x-group优先。kind:控制 Mintlify 如何使用该 tag。nav或没有kind:创建一个导航分组。badge:在侧边栏中端点旁边以标记形式显示该 tag 的summary(如果没有summary,则显示其name)。badge 类型的 tag 不会创建分组。- 任何其他值(例如
audience):既不创建分组,也不显示标记。
kind: nav 的 tag 来放置它。如果没有,Mintlify 会使用第一个已声明且没有 kind 的 tag,然后是第一个未在 tags 中声明的 tag。要为某个端点设置不同的标记,请在 x-mint.metadata 中使用 tag,它优先于 badge 类型的 tag。
如果两个 tag 同名、parent 引用了不存在的 tag,或 parent 引用形成循环,验证将失败。
要选择哪些端点获得页面以及它们的位置,请在导航元素上设置默认 openapi,并在其 pages 中以 METHOD /path 的形式列出端点。你可以将端点与其他页面混合使用。
docs.json
openapi:
docs.json
docs.json
pages 条目视为文件路径。HTTP 方法必须大写。
要从多个规范生成页面,请将每个规范放在各自的导航元素上,并为每个规范设置各自的 directory。如果你将 openapi 设置为数组,Mintlify 只会从数组中的第一个规范生成页面。
docs.json
directory 设置每个生成页面 URL 中的文件夹。如果两个规范共享同一个 directory 并生成相同的页面 URL,其中一个页面会被另一个页面静默替换。请参阅端点 URL 和标题。
Mintlify 不读取 x-tagGroups 扩展。对于包含许多 tag 的规范,请选择一种方式:
- 每个部分一个规范。 将规范按产品领域拆分为多个文件,或使用 Overlay 移除不属于各部分的操作,然后为每个规范设置各自的部分。
- tag 层级。 升级到 OpenAPI 3.2,并将 tag 嵌套在父 tag 之下。
- 列出端点。 在
docs.json中将每个端点列在你想要的分组中。这样你可以完全掌控,但必须自行将新端点添加到docs.json。
x-hidden 或 x-excluded,使其不出现在生成的导航中:
x-hidden: true:端点会获得页面,但该页面不会出现在导航中。任何拥有 URL 的人都可以打开它。适用于你从其他页面链接或与特定用户共享的端点。x-excluded: true:端点不会获得页面。适用于内部端点,或尚未准备好编写文档的端点。
x-excluded 只会移除页面。如果访问者可以访问你的规范文件,被排除的端点仍然包含在其中。
要仅向特定用户组显示端点,请为该操作添加 x-mint.groups。请参阅 OpenAPI 内容过滤。