---
title: "API 参考"
description: "从 OpenAPI 规范生成带路由、带版本的 API 文档。"
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# API 参考

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

<h2 id="openapi">OpenAPI</h2>

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

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

<h3 id="install-with-the-recipe">通过配方安装</h3>

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

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

```sh
npx add api-reference
pnpm dlx add api-reference
yarn dlx add api-reference
bunx add api-reference
```

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

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

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

<h3 id="how-the-pieces-fit">各部分如何配合</h3>

| 文件 | 职责 |
| --- | --- |
| `src/api/openapi.yaml` | API 契约和文档来源。 |
| `astro.config.ts` | 在 Nimbus 配置中声明规范、版本、路由和渲染策略。 |
| `src/content.config.ts` | 将生成的条目注册为 Astro 内容集合。 |
| `src/pages/api/[...slug].astro` | 通过用户拥有的 API 布局渲染 API HTML。 |
| `src/pages/[...slug]/index.md.ts` | Starter 的共享 Markdown 路由。为每个 API 页面提供替代 Markdown 版本。 |
| `src/components/ui/api-*/` | 控制参考页面的外观和交互设计。 |

<h4 id="why-the-specification-is-not-in-srccontent">为什么规范不在 `src/content` 中</h4>

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

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

<h3 id="configuration-generated-by-the-recipe">配方生成的配置</h3>

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

```ts title="astro.config.ts"
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 字段：

```ts title="src/content.config.ts"
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` 条目会重启开发服务器并重新索引参考，无需手动重启。

<h4 id="passing-the-entry-explicitly">显式传递条目</h4>

`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` 条目的编辑。

<h3 id="coordinates-and-routes">坐标和路由</h3>

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

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

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

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

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

```ts
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 或处理无法派生的路径：

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

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

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

<h4 id="link-from-prose-by-coordinate">通过坐标从散文链接</h4>

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

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

Nimbus 在构建期间解析引用：

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

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

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

<h4 id="coordinate-shapes">坐标形式</h4>

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

| API 项 | 坐标示例 |
| --- | --- |
| API 根 | `api` |
| 标签 | `tags.Events` |
| 操作 | `retrieveEvent` |
| 请求体字段 | `retrieveEvent.name` |
| 参数 | `retrieveEvent.path.event_id` |
| 响应 | `retrieveEvent.response.200` |
| 额外媒体类型中的响应字段 | `retrieveEvent.response.200.text-csv.id` |
| Schema | `Event` |
| Schema 字段 | `Event.created_at` |
| Webhook | `delivery.succeeded` |

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

<h3 id="versioned-api-references">版本化 API 参考</h3>

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

```ts title="astro.config.ts"
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 决策变得明确。

<h3 id="build-or-request-rendering">构建或请求渲染</h3>

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

```sh
npx add adapter-cloudflare
pnpm dlx add adapter-cloudflare
yarn dlx add adapter-cloudflare
bunx add adapter-cloudflare
```

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

```ts title="astro.config.ts"
rendering: {
  default: "build",
  collections: {
api: "request",
  },
},
```

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

<h4 id="prepared-code-examples">预处理的代码示例</h4>

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

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

```astro
---
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 要求，请参阅[配置](/configuration#rendering-policy)。

<h3 id="published-outputs">发布的输出</h3>

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

| 路由 | 用途 |
| --- | --- |
| `/api` | 默认版本的 API 概览。 |
| `/api/<page-slug>` | 操作、Schema、标签或 Webhook 页面。 |
| `/api/<page-slug>/index.md` | 干净的 Markdown 版本。 |
| `/api/llms.txt` | 仅 API 的 `llms.txt` 索引。 |
| `/llms.txt` 和 `/llms-full.txt` | 全站页面索引和完整 Markdown 文档。 |
| `/nimbus-api/coordinates.json` | 公开的坐标到 URL 清单。 |

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

<h3 id="cite-an-api-hosted-elsewhere">引用托管在其他地方的 API</h3>

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

```ts
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 或无效的顶级形状会导致构建失败；格式正确的清单中的格式错误条目会产生警告并被忽略。

<h3 id="verify-the-reference">验证参考页面</h3>

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

```sh
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 的开发服务器。

Source: https://nimbus-docs.cn/api-reference/index.mdx