跳转到主要内容
生成的端点页面会从你的 OpenAPI 规范中获取标题、描述、参数和响应。要更改页面显示的内容,你可以:
  • 在规范中为该操作添加 x-mint 扩展。页面仍然是自动生成的,更改与规范保存在一起。
  • 为该端点创建 MDX 页面。适用于少数需要自定义布局的页面,或在单个页面上试验更改。
要更改页面的 URL,请参阅端点 URL 和标题。

覆盖页面元数据

为操作添加 x-mint.metadata 即可覆盖页面的 frontmatter。你可以使用 MDX frontmatter 中除 openapi 以外的任何有效字段。
使用 x-mint.metadata 为单个端点设置试验台显示、访问组或侧边栏中的 tag 标记。

向页面添加内容

使用 x-mint.content 在生成的 API 文档之前添加 Markdown 和 MDX 内容。该内容支持所有 Mintlify 组件。

折叠试验台字段

要让试验台中的嵌套对象字段默认折叠,请在操作上将 x-mint.playground.expand 设置为 false。Authorization、Headers、Query、Path 和 Body 部分以及顶层请求体对象保持展开,读者只需展开他们需要的嵌套字段。默认情况下,对象字段是展开的。
要控制所有端点中可选字段的显示方式,请在 docs.json 中使用 api.optional。

添加参数标记

在任意 schema 上使用 x-mint.pre 和 x-mint.post 为参数添加自定义标记。pre 中的标记显示在参数名称之前,post 中的标记显示在参数名称之后,与 required、read-only 和 write-only 等内置标记并列。数组中的每个字符串都会成为一个单独的标记。
要在每个具有某字段的参数上将该字段显示为标记,请在 docs.json 的 api.params.post 中列出该字段的键:
docs.json
使用此配置后,像 { "type": "string", "nullable": true, "x-internal": "admin" } 这样的属性会在名称旁边显示 nullable 和 admin 标记。post 标记按以下顺序显示:内置标记,然后是 api.params.post 标记,最后是各属性的 x-mint.post 标记。

为端点创建 MDX 页面

如果你希望完全掌控某个页面,同时仍使用自动生成的参数和响应,请为该端点创建 MDX 页面。将 frontmatter 字段 openapi 设置为该页面所记录的操作。
openapi 的值必须是引用单个端点的字符串。如果你将其设置为端点列表或其他非字符串值,部署将失败。方法和路径必须与你的 OpenAPI 规范完全匹配。 像添加其他页面一样将该页面添加到导航中。不要在导航中再列出同一个操作(例如 "GET /users")。
当仓库中有多个 OpenAPI 规范时,请始终包含规范的文件路径。Mintlify 会上传文档仓库中的每个 OpenAPI 规范,即使 docs.json 没有引用它。如果 MDX 页面使用 openapi: "METHOD /path" 而没有文件路径,Mintlify 会在所有已上传的规范中查找匹配的操作。如果多个规范包含相同的方法和路径,则按文件名字母顺序的第一个匹配项为准。为避免错误匹配,请在 frontmatter 中包含文件路径,改为从 docs.json 生成页面,或删除不再需要的规范。
要为规范中的每个端点创建 MDX 文件,请使用 Mintlify scraper。添加 -o 选择输出文件夹。如果不添加,文件会生成在当前目录中。
要将现有的 MDX 端点页面改回自动生成的页面,请参阅将 MDX API 页面迁移到 OpenAPI。

为数据模型创建页面

使用 frontmatter 字段 openapi-schema,为规范 components.schemas 中的 schema 创建页面。
如果多个规范中的 schema 同名,请包含文件路径: