添加 OpenAPI 参考

Nimbus 目前支持 OpenAPI 3.x。Nimbus 会把本地 OpenAPI 文档转换为内容集合，用它驱动参考页面、导航、备用 Markdown 版本、搜索条目、llms.txt 索引以及来自正文文档的稳定链接。

OpenAPI 文档始终是唯一事实来源。你不需要为每个操作或 schema 创建单独的 MDX 文件。

要查看完成的参考示例，请打开天气演示：这是一个 Nimbus 站点，包含一个具有 105 个端点、三个版本的 API，在 Cloudflare Workers 上按请求渲染。

用它创建新站点

脚手架可以为你设置好参考：--api 会把它添加到文档旁边，位于 /api，而 --template api 会让它成为整个站点，位于 /。用 --api ./openapi.yaml 传入你的规格，或省略它以使用示例。参见脚手架选项。

npm create @cloudflare/nimbus-docs@latest -- my-docs --api ./openapi.yaml
npm create @cloudflare/nimbus-docs@latest -- my-docs --template api

使用方案安装

从保存在仓库中的 OpenAPI 3.x 文档开始。如果你有 Swagger 2.0 文档，请先转换它。src/api/openapi.yaml 是常见位置，但 Nimbus 接受任何项目相对本地路径、声明为内容来源的另一个 git 仓库中的文件（spec: { source: "sdk", path: "openapi.json" }），或内联文档对象。不支持远程规格 URL。

在项目根目录的编码智能体中运行 API 参考方案：

npx @cloudflare/nimbus-docs add api-reference
yarn nimbus-docs add api-reference
pnpm nimbus-docs add api-reference
bunx @cloudflare/nimbus-docs add api-reference

在编码智能体中，Nimbus 会把方案直接交给它。在普通 shell 或脚本中，添加 --print 并把输出传给你的智能体。不使用 --print 时，shell 只会得到如何通过管道传递的说明，输出到标准错误，且不会更改任何文件。

该方案会在更改文件前与你确认计划。

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

1. 安装可编辑的 API 布局及其解析器依赖。
2. 在 astro.config.ts 的 Nimbus 配置中声明规格。
3. 用一行注册由 loader 支持的 Astro 内容集合。
4. 添加 HTML catch-all 路由。起始模板的共享 Markdown 路由提供每个页面的 Markdown 版本。
5. 将该集合连接到搜索、备用 Markdown 版本和 llms.txt 索引。

转换 Swagger 2.0 文档

Nimbus 只读取 OpenAPI 3.x。Swagger 2.0 文档会导致构建失败，报错为 Swagger 2.0 isn't supported. Convert it to OpenAPI 3.x first.，后面跟着文档路径。

把 Swagger 文档保留为源，并使用 swagger2openapi 从中生成单独的 OpenAPI 3.x 文档：

npm i -D swagger2openapi@7.0.8
yarn add -D swagger2openapi@7.0.8
pnpm add -D swagger2openapi@7.0.8
bun add -d swagger2openapi@7.0.8

在 dev 和 build 脚本中，于 Astro 之前运行转换，使生成的文档始终与源匹配：

{
  "scripts": {
    "dev": "swagger2openapi src/api/swagger.yaml --yaml --outfile src/api/openapi.yaml && astro dev",
    "build": "swagger2openapi src/api/swagger.yaml --yaml --outfile src/api/openapi.yaml && astro build"
  }
}

把 api 条目的 spec 指向生成的文档 ./src/api/openapi.yaml。转换器会把 host、basePath 和 schemes 转为 servers，把 body 和 form 参数移入请求体，并转换安全定义。开发服务器监视生成的文档，而不是 Swagger 源，因此编辑源后请重启 dev。

各部分如何协作

为什么规格不放在 src/content

src/content/docs/ 包含手写的 MDX 条目。OpenAPI 文档是 loader 的输入：Nimbus 会把它投影为注册的 api 集合中的许多操作、标签和 webhook 条目，并在开启 schema 页面时投影为 schema 条目。

把源放在 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)],
});

参考会按其路由文件所在位置提供：src/pages/api/[...slug].astro 在 /api 提供 api，src/pages/reference/api/[...slug].astro 在 /reference/api 提供它，版本、openapi.json 和 API 目录都位于其下。参见集合 URL。

该方案随后在同一个键下注册由 loader 支持的集合，保留已有的集合和自定义 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 哪个 loader 把该条目转换为内容条目，并让 Nimbus 在配置和构建验证期间找到该集合。

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

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

验证参考

添加或更改规格后，运行生产构建：

pnpm build

确认以下各项：

1. 构建报告索引的 API 页面数量。
2. 参考首页和一个操作页面能够渲染：/api，或在只有参考的站点中为 /。
3. 同一操作的 /index.md 路由返回 Markdown。
4. 参考的 llms.txt 列出其页面：/api/llms.txt，或根路径的 /llms.txt。
5. /nimbus-api/coordinates.json 包含一个已知的操作 ID。
6. 在带文档的站点中，正文的 api.ref: 链接解析到预期路由。

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

后续步骤

• 路由与坐标：为页面选择 URL。
• 引用 API 页面：从指南中链接到操作。
• 代码示例：控制每个操作上的示例。