OpenAPI 选项

Nimbus 配置中的每个 api 条目声明一个 API 参考。要设置它，参见添加 OpenAPI 参考。

`api` 条目

键	类型	默认值	作用
`collection`	`string`	—	必填。内容集合键，与 `src/content.config.ts` 中的 `apiCollection()` 匹配。
`spec`	`string` \| `{ source, path }` \| object	—	OpenAPI 3.x 文档：项目相对路径、内容来源中的文件，或内联对象。设置 `versions` 时省略。
`versions`	`ApiVersion[]`	—	用版本家族代替单个 `spec`。参见 API 版本。
`versionUrl`	`{ in: "path" }` \| `{ in: "query", param? }`	`{ in: "path" }`	版本在 URL 中的位置。查询模式需要按请求渲染。
`label`	`string`	`collection`	构建消息中该 API 的名称。
`requireOperationId`	`boolean`	`false`	当操作没有 `operationId` 时使构建失败，而不是从其方法和路径推导坐标。
`routes`	`{ convention, stripPathPrefixes?, operations?, sections?, tagSegments? }`	—	路由约定。参见路由与坐标。
`sidebar`	`"full"` \| `"on-demand"`	`"full"`	每个页面包含多少导航。参见大型 API。
`schemaPages`	`boolean`	`false`	为每个 schema 发布页面，并让 schema 可被引用。
`samples`	`{ generate?, keepGenerated? }`	全部三种语言	Nimbus 生成哪些代码示例。参见代码示例。
`extensions`	`string[]`	—	要复制到页面上的 `x-*` 字段。参见供应商扩展。
`publishSpec`	`boolean`	`true`	将规格发布为 JSON，并在 API 目录中列出。
`bundle`	`boolean`	`true`	`false` 会把页面数据存储为静态资源，按请求读取。需要按请求渲染和 Cloudflare 或 Node 适配器。参见大型 API。

versions 中的每一项：

键	类型	默认值	作用
`version`	`string`	—	必填。版本 id：小写字母、数字、点和短横线，并以字母或数字开头和结尾。它是每个非默认 URL 的一部分。
`spec`	`string` \| `{ source, path }` \| object	—	必填。该版本的文档。
`default`	`boolean`	第一个版本	在家族自己的路径提供此版本。默认版本不能是 `hidden`。
`status`	`"ga"` \| `"beta"` \| `"deprecated"`	—	`deprecated` 会在该版本的每个页面上显示横幅。
`hidden`	`boolean`	`false`	使版本不出现在选择器、搜索和站点地图中。其页面仍可加载。
`label`	`string`	`version`	版本在选择器中的名称。
`routes`	同上	—	该版本的路由约定。
`publishSpec`	`boolean`	条目的值	覆盖条目的 `publishSpec`。
`extensions`	`string[]`	条目的值	替换条目的 `extensions` 列表。

每个集合都会把其规格发布为一个自包含的 JSON 文件，位于 /api/openapi.json（根路径的参考为 /openapi.json），各版本位于其自己的挂载路径，并在站点的 API 目录中列出。在集合或单个版本上设置 publishSpec: false，可使该规格不被发布：

astro.config.tsts

api: [
  {
    collection: "api",
    spec: "./src/api/openapi.yaml",
    publishSpec: false,
  },
],

对于名为 api 的集合，当存在相应的起始模板路由时，参考会与以下路由集成：

路由	用途
`/api`	默认版本的 API 概览。
`/api/<page-slug>`	操作、标签或 webhook 页面，以及开启 `schemaPages: true` 时的 schema 页面。
`/api/<page-slug>/index.md`	干净的 Markdown 版本。
`/api/llms.txt`	仅含 API 的 `llms.txt` 索引。
`/llms.txt` 和 `/llms-full.txt`	站点范围的页面索引和完整 Markdown 文档。
`/nimbus-api/coordinates.json`	公开的坐标到 URL 清单。
`/api/index/<n>/`	API 首页的后续部分（`noindex`）。
`/api/openapi.json`	发布的规格；其他版本位于 `/api/<version>/openapi.json`。参见发布的规格。
`/.well-known/api-catalog` 和 `/.well-known/ard.json`	站点的 API 目录和发现清单，列出每个可见版本。

当项目中启用相关功能时，API 条目也会加入现有的 Pagefind 搜索、站点地图和 OG 图片路由。