---
title: "添加 OpenAPI 参考"
description: "把本地 OpenAPI 3.x 文档接入 Nimbus，生成参考页面、导航、Markdown 版本与搜索条目。"
---

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

# 添加 OpenAPI 参考

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

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

要查看完成的参考示例，请打开[天气演示](https://demo.nimbus-docs.com/api/)：这是一个 Nimbus 站点，包含一个具有 105 个端点、三个版本的 API，在 Cloudflare Workers 上按请求渲染。

## 用它创建新站点

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

```sh
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 文档，请先[转换它](#convert-a-swagger-20-document)。`src/api/openapi.yaml` 是常见位置，但 Nimbus 接受任何项目相对本地路径、声明为[内容来源](/content-sources/git/#api-specs-from-a-source)的另一个 git 仓库中的文件（`spec: { source: "sdk", path: "openapi.json" }`），或内联文档对象。不支持远程规格 URL。

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

```sh
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](https://github.com/Mermade/oas-kit/tree/main/packages/swagger2openapi) 从中生成单独的 OpenAPI 3.x 文档：

```sh
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 之前运行转换，使生成的文档始终与源匹配：

```json title="package.json"
{
  "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/api/openapi.yaml` | API 契约和文档来源。 |
| `astro.config.ts` | 在 Nimbus 配置中声明规格、版本、路由和渲染策略。 |
| `src/content.config.ts` | 将生成的条目注册为 Astro 内容集合。 |
| `src/pages/api/[...slug].astro` | 通过用户自有的 API 布局渲染 API HTML，包括 [API 首页](/api-reference/large-apis/#the-api-home)的后续部分。 |
| `src/pages/[...slug]/index.md.ts` | 起始模板的共享 Markdown 路由。提供每个 API 页面的备用 Markdown 版本。 |
| `src/components/ui/api-*/` | 拥有参考的外观和交互设计。 |

### 为什么规格不放在 `src/content`

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

把源放在 `src/api/` 下能让这种区别一目了然。路径只是约定；如果配置的 `spec` 指向那里，`src/content/api/openapi.yaml` 同样可行。

## 方案生成的配置

该方案只声明一次规格，作为 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)],
});
```

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

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

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

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

## 验证参考

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

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

## 后续步骤

- [路由与坐标](/api-reference/openapi/routes/)：为页面选择 URL。
- [引用 API 页面](/api-reference/citations/)：从指南中链接到操作。
- [代码示例](/api-reference/openapi/code-samples/)：控制每个操作上的示例。

Source: https://nimbus.ndjp.net/api-reference/openapi/setup/index.mdx