# @dunx/openapi 中文文档

规范地址：https://npmcn.com/package/%40dunx/openapi/

版本：3\.10\.6
npm 元数据更新时间：2026-10-30T04:59:30.064Z
中文译文更新时间：2026-11-13T00:26:35.723Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dunx/openapi
原文对照：https://npmcn.com/package/%40dunx/openapi/?lang=original
项目主页：https://github.com/petarzarkov/dunx/tree/main/packages/openapi#readme
源码仓库：https://github.com/petarzarkov/dunx

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：113 kB，33 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：zod ^4，@dunx/core ^3\.10\.6，@dunx/http ^3\.10\.6，@types/bun \>=1\.4\.3，swagger-ui-dist ^5\.32\.14，@scalar/api-reference ^1\.68\.0
- 首次发布：2026-08-02T08:08:14.969Z
- 最新版本发布：2026-10-30T04:59:29.726Z
- 近 30 天下载量：4467（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：83（近 12 个月 83 个）

## 中文简介

用于 dunx 控制器的 OpenAPI 3.1 文档, 由已验证的路由的计程器生成, 上面挂有 Swagger UI 或 Scalar

## 安装

```sh
npm install @dunx/openapi
```

也可以使用：`pnpm add @dunx/openapi`、`yarn add @dunx/openapi`、`bun add @dunx/openapi`

## README

# @ dunx/ openapi (帮助)

应用程序已经拥有的路径生成的 OpenAPI 3.1 文件 **Swagger 用户界面** 或者说 **斯卡尔** 从同一地点任职 `Bun.serve` 作为其他一切.

与基于反射的生成器的区别在于它所读到的. 一条路线 策略是请求路径验证的对象 。 其安全性 元数据 (`@Public()`, (中文(简体) ), `@Roles()`这是它所执行的。 两个都已经 因此文档不是第二个可以漂移的描述 第一个.

## 安装

```bash
bun add @dunx/openapi zod
```

`zod` 是同级依赖。 路线验证目标 标准Schema, 所以 Valibot 和 ArkType 进行验证,但 OpenAPI 文件需要 JSON Schema, 只有佐德已经 `z.toJSONSchema`。在运行时间和 显示为文档中允许的条目,并在生成时发出警告.

文档UI是选择输入的,每个子路径有一个可选的对等点. 安装一个你 挂载,或无:

| 导入 | 渲染器 | 要安装的对等点 |
| --- | --- | --- |
| `@dunx/openapi/swagger` | `SwaggerRenderer` | `swagger-ui-dist` |
| `@dunx/openapi/scalar` | `ScalarRenderer` | `@scalar/api-reference` |

## 使用量

```ts
import { HttpFactory } from '@dunx/http';
import { OpenApiModule } from '@dunx/openapi';
import { SwaggerRenderer } from '@dunx/openapi/swagger';

const app = await HttpFactory.create(
  OpenApiModule.forRoot({
    title: 'Payments',
    version: '1.4.0',
    root: AppModule, // the graph to document, and the graph that gets imported
    // Omit for the document alone: no `renderer`, no page route.
    renderer: new SwaggerRenderer({ docExpansion: 'list' }),
  }),
);
app.setGlobalPrefix('api');
await app.listen(3000);
// GET /api/docs          the explorer
// GET /api/openapi.json  the document
```

`forRootAsync` 所以一个应用软件可以读出它的标题 `ConfigService` 或者提供另一个图书馆的计划.

## 这是什么

这个 [OpenAPI 指南](https://npmcn.com/package/docs/guide/10-openapi.md) 简直太夸张了.

| 块 | 它会做什么 |
| --- | --- |
| `OpenApiModule` | 包扎其文档根,挂载 JSON 和 a `renderer`页面 |
| `DocsRenderer` | 页面合同. `PackageAssets` 为渲染器的文件服务 |
| `@ApiDoc` | 路线或类别上的概要、说明、标记和折旧 |
| `@ApiHidden` | 一个真实的路径 远离文档。 住在这里 `@dunx/http` |
| `describeRoutes` | 路径作为数据, 构建无 |
| `generateDocument` | 这些路线的文件 |
| `betterAuthDocument` | 更好的奥斯自己的路径 合并在一起。 住在这里 `@dunx/auth` |
| `bunx dunx-openapi` | 写入文件的文档, 没有容器和服务器 |

安全来自同一个地方 `@Public()` 财务报告和审定财务报表 `@Roles()` 守护者读取的元数据 在运行时间,所以文档没有第二个注释可以不同意. 响应计划只是文档: 动词装饰者持有处理器 在编译时返回类型,而不是验证每个响应.

`authorize` 决定谁可以看到文档、页面和页面的资产。 这个 一样 `Authorize` 作为 `@dunx/dashboard`被拒绝的请求得到404。 若为 `authorize` 返回 a `Response`,例如重定向以签名,该响应 现按原样发送.

## 页:1

-   添加 `.meta({ id })` 把它放进去 `components/schemas`没有 无论它在哪里使用,它都是内在的. `.strict()` 之后 `.meta()` 丢弃 元数据,所以调用 `.meta()` 最后一个.
-   Prose属于 `description`。一个探险家将一个图案标注为 `title`,哪个 `@dunx/openapi` 填入组件名称.
-   页面嵌入文档而不是取回,并装入渲染器的 文件来自您自己的安装。 没到CDN 除非你转身 斯卡尔的 `withDefaultFonts` 继续.
-   `renderer` 坐在旁边 `root` 而不是在 `forRootAsync`工厂: 控制器在有容器运行之前宣布其路线.

## 许可证

麻省理工学院

## 常见问题

### @dunx/openapi 是什么？

用于 dunx 控制器的 OpenAPI 3\.1 文档, 由已验证的路由的计程器生成, 上面挂有 Swagger UI 或 Scalar

### 如何安装 @dunx/openapi？

在项目目录运行 npm install @dunx/openapi，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@dunx/core（^3\.10\.6）、@dunx/http（^3\.10\.6）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 dunx-openapi，可以用 npx dunx-openapi 直接运行。

### @dunx/openapi 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dunx/openapi 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dunx/openapi 可以商用吗？

@dunx/openapi 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dunx/openapi 的下载量有多少？

根据 npm 官方下载统计，@dunx/openapi 在 2026/10/13 – 2026/11/11 这 30 天内被下载 4,467 次，日均约 149 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dunx/openapi 还在维护吗？

最新版本 3\.10\.6 发布于 2026/10/30（14 天前）；至今共发布 83 个版本，其中过去 12 个月发布了 83 个；首次发布于 2026/08/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。