users、summary 为 Get user 的操作,其 URL 为 /api-reference/users/get-user。
- Directory:你在
docs.json的openapi字段上设置的directory,使用小写形式。默认值为api-reference。 - Tag:操作所属 tag 的
name。来自x-group、x-displayName或 3.2 tagsummary的标签不会改变 URL。如果操作没有 tag,URL 就没有 tag 部分。关于操作有多个 tag 时 Mintlify 使用哪一个,请参阅使用 tag 层级嵌套分组。OpenAPI 3.2 中的父 tag 不会为 URL 增加部分。 - Slug:操作的
summary,经过转换后用于 URL。如果操作没有 summary,Mintlify 会使用 HTTP 方法和路径。例如,GET /users/{id}/posts会变为get-users-posts。
{、}、(、)、,、.、' 和 /,并将结果转换为小写。其他字符(例如 ?、&、: 和非 ASCII 字母)会保留在 URL 中。要获得可预测的 URL,请使用由字母、数字和空格组成的 summary 和 tag 名称,或使用操作 ID。
如果同一分组中的两个端点生成了相同的 URL,Mintlify 会为后面的端点添加 -1、-2 等后缀。在某些情况下,一个页面会直接替换另一个页面,而不会报错:
- 两个规范共享同一个
directory,或同一个规范在导航中的两个位置使用。 - 带有
x-hidden的端点与另一个端点生成了相同的 URL。
directory。
将 slug 设置为 operationId,即可根据每个操作的 operationId 而不是 summary 来构建 slug。这样你就可以编辑 summary 而不改变 URL。
docs.json
getActions 会变为 get-actions,create_action 会变为 create-action。Mintlify 会删除任何非 ASCII 字母或数字的字符。没有 operationId 的操作使用 summary。directory 和 tag 部分不会改变。
为操作添加 x-mint.href 即可设置其完整 URL。该 URL 会替换 directory、tag 和 slug。
. 之后的所有内容,因此 /reference/v1.2 会变为 /reference/v1。请不要在最后一段中使用点号。
生成页面的标题是操作的 summary。如果没有 summary,Mintlify 会根据 URL slug 构建标题。要设置不同的标题或侧边栏标签,请使用 x-mint.metadata:
New PR Opened 会生成标题 New pr opened。设置 x-mint.metadata.title 即可保留 summary 的格式。
如果你在多个语言中使用同一个规范,除非每种语言都有自己的 directory,否则所有语言都会链接到相同的页面。要为每种语言生成单独的页面(例如基于翻译后的规范),请为每种语言设置不同的 directory。
翻译后的 summary 会生成不同的 slug,因此除非你使用操作 ID,否则同一页面在不同语言中的 URL 会不同。
为避免在规范变化时破坏链接:
- 将
slug设置为operationId,并保持操作 ID 稳定。 - 保持 tag 名称稳定。使用
x-group更改分组标签而不改变 URL。 - 对于 URL 永远不能改变的端点,使用
x-mint.href。 - 当 URL 确实发生变化时,从旧 URL 添加重定向。