- 在规范中为该操作添加
x-mint扩展。页面仍然是自动生成的,更改与规范保存在一起。 - 为该端点创建 MDX 页面。适用于少数需要自定义布局的页面,或在单个页面上试验更改。
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 页面。将 frontmatter 字段 openapi 设置为该页面所记录的操作。
openapi 的值必须是引用单个端点的字符串。如果你将其设置为端点列表或其他非字符串值,部署将失败。方法和路径必须与你的 OpenAPI 规范完全匹配。
像添加其他页面一样将该页面添加到导航中。不要在导航中再列出同一个操作(例如 "GET /users")。
要为规范中的每个端点创建 MDX 文件,请使用 Mintlify scraper。添加 -o 选择输出文件夹。如果不添加,文件会生成在当前目录中。
openapi-schema,为规范 components.schemas 中的 schema 创建页面。