API 参考

Nimbus 从机器可读的规范生成 API 参考。每种受支持的格式都有自己的来源、配置和内容加载器。

OpenAPI

Nimbus 目前支持 OpenAPI 3.x。Nimbus 将本地 OpenAPI 文档转换为内容集合，驱动参考页面、导航、替代 Markdown 版本、搜索条目、llms.txt 索引以及从散文文档到 API 的稳定链接。

OpenAPI 文档始终是数据的唯一来源。你不需要为每个操作或 Schema 创建一个 MDX 文件。

通过配方安装

从存储在你仓库中的 OpenAPI 3.x 文档开始。如果使用 Swagger 2.0 文档，请先转换为 OpenAPI 3.x。src/api/openapi.yaml 是常见的存放位置，但 Nimbus 接受任何项目相对路径或内联文档对象。不支持远程规范 URL。

在你的编码智能体中，从项目根目录运行 API 参考配方：

npx @cloudflare/nimbus-docs add api-reference

yarn dlx @cloudflare/nimbus-docs add api-reference

pnpm dlx @cloudflare/nimbus-docs add api-reference

bunx @cloudflare/nimbus-docs add api-reference

Nimbus 会将配方直接传递给检测到的编码智能体。在普通 shell 中，添加 --print 并将输出传递给你的编码智能体。配方会在修改文件之前审查其计划。

该配方会让智能体检查你的项目、询问规范路径和集合名称，然后：

1. 安装可编辑的 API 布局及其解析器依赖。
2. 在 astro.config.ts 的 Nimbus 配置中声明规范。
3. 用一行代码注册一个加载器驱动的 Astro 内容集合。
4. 添加 HTML 通配路由。Starter 的共享 Markdown 路由为每个页面提供 Markdown 版本。
5. 将集合连接到搜索、替代 Markdown 版本和 llms.txt 索引。

各部分如何配合

为什么规范不在 src/content 中

src/content/docs/ 包含手工编写的 MDX 条目。OpenAPI 文档是加载器的输入：Nimbus 将其投影到已注册的 api 集合中的多个操作、Schema、标签和 Webhook 条目。

将源文件放在 src/api/ 下使这种区别一目了然。这只是一种惯例；如果配置的 spec 指向 src/content/api/openapi.yaml，也同样有效。

配方生成的配置

配方在 Nimbus 配置中声明一次规范，作为 api 条目：

import { defineConfig } from "astro/config";
import nimbus, {
  defineConfig as defineNimbusConfig,
} from "@cloudflare/nimbus-docs";

const nimbusConfig = defineNimbusConfig({
  site: "https://docs.example.com",
  title: "Acme Docs",
  api: [
    {
      collection: "api",
      spec: "./src/api/openapi.yaml",
    },
  ],
});

export default defineConfig({
  integrations: [nimbus(nimbusConfig)],
});

集合名称同时也是其 URL 前缀：api 将参考页面挂载到 /api。

然后，配方在相同的键下注册一个加载器驱动的集合，同时保留现有集合和自定义 Schema 字段：

import { defineCollection } from "astro:content";
import {
  apiCollection,
  docsCollection,
  partialsCollection,
} from "@cloudflare/nimbus-docs/content";

export const collections = {
  docs: defineCollection(docsCollection()),
  partials: defineCollection(partialsCollection()),
  api: defineCollection(apiCollection()),
};

apiCollection() 读取 collection 与其键匹配的 api 条目，因此规范只需声明一次。该键告诉 Astro 使用哪个加载器将条目转换为内容条目，并让 Nimbus 在配置和构建验证期间找到集合。

要挂载多个规范，为每个规范添加一个 api 条目和一行 apiCollection()。如果集合键没有对应的 api 条目，或者 api 条目在其键下没有匹配的 apiCollection()，构建将失败。错误信息会指出两个文件。nimbus-docs check 无需构建即可报告相同的不匹配。

在 astro dev 中，编辑规范文件会重新索引其页面。编辑 api 条目会重启开发服务器并重新索引参考，无需手动重启。

显式传递条目

apiCollection() 也直接接受条目：apiCollection({ collection: "api", spec: "./src/api/openapi.yaml" })。早期版本配方创建的站点使用这种形式，Nimbus 配置在单独的 nimbus.config.ts 中，使用 @cloudflare/nimbus-docs/config 的 defineConfig 构建。它们的构建不受影响。将配置移回 astro.config.ts 并切换到 apiCollection() 可以让 nimbus-docs check 静态验证配置，让 add adapter-cloudflare 就地编辑，并在 astro dev 中重新索引对 api 条目的编辑。

坐标和路由

Nimbus 将标识和路由分开处理。坐标在引用、跨版本匹配、锚点和坐标清单中标识 API 项。路由是其生成页面的 URL。

操作使用其 OpenAPI operationId 作为坐标：

paths:
  /v1/events/{event_id}:
    get:
      operationId: retrieveEvent
      summary: Retrieve an event
      tags: [Events]

此操作的坐标是 retrieveEvent。在没有路由策略的情况下，其第一个标签和操作 ID 生成 /api/Events/retrieveEvent。

可选的 resource-action-v1 策略改为从 HTTP 方法和路径派生路由：

api: [
  {
    collection: "api",
    spec: "./src/api/openapi.yaml",
    requireOperationId: true,
    routes: {
      convention: "resource-action-v1",
      stripPathPrefixes: ["/v1"],
    },
  },
],

这里，Nimbus 移除 /v1 并将操作发布到 /api/events/retrieve；其坐标仍然是 retrieveEvent。

派生逻辑在移除前缀后识别 /<resource> 和 /<resource>/{parameter} 模式。它将集合 GET/POST 映射为 list/create，将成员 GET/PUT/PATCH/DELETE 映射为 retrieve/update/update/delete。标签不影响策略路由。其他模式或不支持的方法/模式组合通常回退到规范化的坐标，并产生构建警告；如果该坐标无法生成非空路由，构建将失败。

显式的操作覆盖（以精确可用的 operationId 为键）优先级最高，可以保留现有 URL 或处理无法派生的路径：

routes: {
  convention: "resource-action-v1",
  operations: {
    retrieveEvent: "events/get",
  },
},

如果没有可用的 operationId，Nimbus 从方法和路径派生一个回退坐标。requireOperationId: true 拒绝该回退，但更改现有操作 ID 仍然会改变坐标。Webhook 始终使用其映射键作为坐标，并发布在 webhooks/<key> 下；为 Webhook 配置操作覆盖会导致构建失败。

重命名坐标需要更新引用，并影响跨版本匹配。仅更改路由会使基于坐标的引用保持不变，但会破坏指向先前 URL 的直接链接。Nimbus 不会自动创建该重定向；请在 Astro 或部署平台上添加。

通过坐标从散文链接

在 src/content 下的 Markdown 或 MDX 中使用 api.ref: 目标：

See how to [retrieve an event](api.ref:api:retrieveEvent).

Nimbus 在构建期间解析引用：

• api 标识 API 集合。
• retrieveEvent 独立于其路由标识操作。
• 不带版本的引用指向 API 系列的默认版本。
• 已知集合中的未知坐标会导致手工内容构建失败，并可能建议一个接近的匹配。
• 未知集合会产生警告并重写为 #；对照 /nimbus-api/coordinates.json 验证集合名称，以确保无效引用不会发布。

仅在散文专门讨论某个历史版本时才固定该版本：

Review the [v1 operation](api.ref:api@v1:retrieveEvent).

坐标形式

操作不是唯一可寻址的项目。Nimbus 为页面及其内部细节分配坐标：

使用 /nimbus-api/coordinates.json 检查构建站点发布的精确坐标和解析后的 URL。

版本化 API 参考

API 版本位于 api 条目内部。这与用于手工编写的散文文档的顶级 versions 选项是分开的。一个条目接受 spec（单个版本）或 versions（版本系列），但不能同时使用两者。此示例使用默认的操作 ID 路由；路由策略在每个版本上独立设置：

api: [
  {
    collection: "api",
    label: "Acme API",
    requireOperationId: true,
    versions: [
      {
        version: "v2",
        spec: "./src/api/openapi-v2.yaml",
        default: true,
        status: "ga",
      },
      {
        version: "v1",
        spec: "./src/api/openapi-v1.yaml",
        status: "deprecated",
      },
    ],
  },
],

标记为 default: true 的版本拥有 /api；其他版本挂载在其版本下，如 /api/v1。如果没有标记任何版本，则第一个版本为默认版本。当页面共享坐标时，Nimbus 会在版本之间链接页面。已弃用的版本会在参考 UI 中渲染其状态。

路由策略属于版本系列中的每个版本。当两个规范使用不同的基础路径或需要不同的覆盖时，这使 URL 决策变得明确。

构建或请求渲染

API HTML 默认预渲染。请求渲染首先需要 Cloudflare 适配器配方：

npx @cloudflare/nimbus-docs add adapter-cloudflare

yarn dlx @cloudflare/nimbus-docs add adapter-cloudflare

pnpm dlx @cloudflare/nimbus-docs add adapter-cloudflare

bunx @cloudflare/nimbus-docs add adapter-cloudflare

配置服务器输出后，此策略仅在请求时渲染 API 集合：

rendering: {
  default: "build",
  collections: {
    api: "request",
  },
},

配方的 API 通配路由使用 Nimbus 运行时辅助函数来处理两种模式。请求渲染仅更改规范 HTML 页面。替代 Markdown 版本、坐标数据、搜索记录、站点地图和 llms.txt 索引仍然是构建产物，请求消费预处理的内容条目而不是解析 OpenAPI 文档。

预处理的代码示例

apiCollection() 在构建内容索引时高亮请求示例、主要和命名的请求示例、响应以及额外请求体和响应媒体类型的示例。OpenAPI requestBody.content.*.*.examples 条目作为 ApiOperationPage.requestExamples 可用，保留每个键、摘要、描述、媒体类型和内联值。不会获取仅外部的示例。

用户拥有的渲染器应使用 Astro 的 set:html 渲染 highlightedHtml，而不是在请求渲染的路由中导入 Shiki 或 Astro 的 Code 组件：

---
import type { ApiOperationPage } from "@cloudflare/nimbus-docs/api";

interface Props extends Pick<ApiOperationPage, "samples"> {}

const { samples } = Astro.props;

function preparedCode(value: { highlightedHtml?: string }): string {
  if (!value.highlightedHtml) {
    throw new Error("Nimbus API code was not prepared during content sync.");
  }
  return value.highlightedHtml;
}
---

{samples.map((sample) => (
  <Fragment set:html={preparedCode(sample)} />
))}

缺少预处理值表明 API 索引过期或构建不正确。更改规范或 API 渲染器类型后请重新构建。

有关 Cloudflare 适配器和 Wrangler 要求，请参阅配置。

发布的输出

对于名为 api 的集合，当相应的 Starter 路由存在时，参考页面与以下路由集成：

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

引用托管在其他地方的 API

文档站点可以引用由另一个 Nimbus 站点发布的参考，而无需挂载或重新发布它：

apiReferences: [
  {
    collection: "api",
    manifest: "https://api.example.com/nimbus-api/coordinates.json",
    origin: "https://api.example.com",
  },
],

collection 必须与远程清单发布的集合键匹配。origin 是添加到站点相对清单路径的绝对前缀。当远程参考托管在某个基础路径下时，请包含该部署基础路径，例如 https://api.example.com/docs。

然后，远程集合使用相同的散文语法：api.ref:api:retrieveEvent。远程引用仅提供引用目标；它们不会将远程页面添加到本地搜索或智能体输出中。

Nimbus 在构建期间获取 HTTPS 清单。不可用或格式错误的远程清单会产生警告，其引用解析为 #；它不会阻止构建。如果构建必须离线工作，你可以改为提交清单并使用项目相对路径。不可读的本地清单、无效 JSON 或无效的顶级形状会导致构建失败；格式正确的清单中的格式错误条目会产生警告并被忽略。

验证参考页面

在添加或更改规范后运行生产构建：

pnpm build

确认以下内容：

1. 构建报告了已索引的 API 页面数量。
2. /api 和一个操作页面可以渲染。
3. 同一操作的 /index.md 路由返回 Markdown。
4. /api/llms.txt 列出了参考页面。
5. /nimbus-api/coordinates.json 包含已知的操作 ID。
6. 散文中的 api.ref: 链接解析到预期的路由。

对于请求渲染，请使用 Wrangler 在本地测试生产 Worker，而不是仅依赖 Astro 的开发服务器。