自定义 API 参考布局
自定义 API 参考布局
自定义 API 参考布局
当您在 docs.yml 文件中包含 API 时，您可以自定义端点和章节在侧边栏导航中的显示方式。默认情况下，参考文档将根据 API 规范的结构生成导航层次结构，但可以配置多种自定义选项。
对于 OpenAPI 规范，章节是基于 tags 属性创建的，转换为 lowerCamelCase 约定（例如，createUser）。
如果您只想显示端点的子集，请阅读更多关于 OpenAPI 规范 的 Audiences 属性。
要按字母顺序对所有章节和端点进行排序（除非在 layout 中明确排序），请将 alphabetized 设置为 true。
layout 选项允许您指定子包、章节、端点和页面在 API 参考顶级的顺序。
如果您的 API 使用命名空间，请在端点前加上命名空间和 ::：
您可以使用 METHOD /path 格式引用端点。
默认情况下，章节显示名称来自 OpenAPI 规范中的标签名称。
要覆盖章节的显示名称，请在 docs.yml 中使用 section 属性。
您也可以使用 x-displayName 扩展直接在规范（或覆盖文件）中自定义标签显示名称。
要删除 API 参考标题并显示章节内容，请将 flattened 设置为 true。
要自定义端点的显示，您可以添加 title。您还可以使用 slug 来自定义端点 URL。
您可以通过将 hidden 设置为 true 来从 API 参考中隐藏端点。该端点仍可通过其 URL 访问，但会自动从搜索引擎索引中排除（noindex），因此您无需设置 noindex。
您可以通过向 API 参考布局添加 section 在侧边栏中添加任意文件夹。一个章节可以包含整组端点、单个端点，甚至只是 Markdown 页面。章节可以通过添加 icon、summary、slug（或 skip-slug）、availability 和 contents 等属性进行自定义。
您可以通过两种方式为 API 参考或单个章节添加概述页面：
summary 属性允许您添加 .md 或 .mdx 页面作为概述。
如果您使用 OpenAPI 规范，设置 tag-description-pages: true 以使用标签描述作为每个章节的摘要页面。
如果您启用 tag-description-pages: true 并手动为章节指定 summary，手动摘要将优先。
您可以在 API 参考中添加常规页面和外部链接。
您可以为整个 API 参考或特定章节设置可用性。选项有：stable、generally-available、in-development、pre-release、deprecated 或 beta。
当您为章节设置可用性时，该章节中的所有端点将继承章节级别的可用性，除非在 API 定义中明确覆盖。
您不能在 docs.yml 中为单个 OpenAPI 端点设置可用性 — 端点可用性必须直接在您的 API 定义中配置。了解更多关于 OpenAPI 的可用性。
将 display-errors 设置为 true 以在端点页面上显示错误模式。错误名称、状态码和响应对象从您的 API 定义中提取。
点击错误会展开它以显示错误名称、代码和返回的对象。响应也会更新以显示错误对象。
以下属性可以在您的 docs.yml 导航中的 - api 条目上设置。
当为 true 时，按字母顺序组织所有章节和端点。
API 参考章节的标题。
受众列表，确定在您的 API 参考中显示哪些端点、模式和属性。
为整个 API 参考或特定章节设置可用性状态。
在 API 参考的端点页面上显示错误模式。
在顶层显示所有端点并隐藏 API 参考章节标题。
在导航中 API 章节旁边显示的图标。
自定义 API 端点在文档站点中的显示顺序。详见排序 API 参考。
当为 true 时，跳过 API 章节的 slug 生成。
自定义 API 章节的 slug。默认情况下，slug 从 API 标题生成。
显示在 API 章节顶部的 Markdown 文件的相对路径。
当为 true 时，使用 OpenAPI 标签描述作为每个章节的摘要页面。
仅在您的项目有多个 API 时使用。该值必须与包含 API 定义的文件夹名称匹配。如果您只有单个 API，请不要设置此属性，否则会导致错误。