# @blgc/openapi-router 中文文档

规范地址：https://npmcn.com/package/%40blgc/openapi-router/

版本：0\.1\.0
npm 元数据更新时间：2025-01-21T14:20:37.165Z
中文译文更新时间：2026-11-08T15:00:07.785Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40blgc/openapi-router
原文对照：https://npmcn.com/package/%40blgc/openapi-router/?lang=original
项目主页：https://builder.group/?source=package-json
源码仓库：https://github.com/builder-group/monorepo

弃用说明：Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

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

- 包体积（解压后）：37.1 kB，44 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2024-08-02T15:20:14.158Z
- 最新版本发布：2024-12-22T13:06:09.317Z
- 近 30 天下载量：1772（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 0 个）

## 中文简介

紧绕快递和Hono等网络框架的路由器,提供OpenAPI类型安全和与Valibot和Zod等验证库的无缝整合

## 安装

```sh
npm install @blgc/openapi-router
```

也可以使用：`pnpm add @blgc/openapi-router`、`yarn add @blgc/openapi-router`、`bun add @blgc/openapi-router`

## README

# ![@blgc/openapi-router banner](https://raw.githubusercontent.com/builder-group/monorepo/develop/packages/openapi-router/.github/banner.svg)

 [![GitHub License](https://img.shields.io/github/license/builder-group/monorepo.svg?label=license&style=flat&colorA=293140&colorB=FDE200)](https://github.com/builder-group/monorepo/blob/develop/LICENSE)[![NPM bundle minzipped size](https://img.shields.io/bundlephobia/minzip/@blgc/openapi-router.svg?label=minzipped%20size&style=flat&colorA=293140&colorB=FDE200) ](https://www.npmjs.com/package/@blgc/openapi-router)[![NPM total downloads](https://img.shields.io/npm/dt/@blgc/openapi-router.svg?label=downloads&style=flat&colorA=293140&colorB=FDE200) ](https://www.npmjs.com/package/@blgc/openapi-router)[![Join Discord](https://img.shields.io/discord/795291052897992724.svg?label=&logo=discord&logoColor=000000&color=293140&labelColor=FDE200)](https://discord.gg/w4xE3bSjhQ)

> 状况:实验

`@blgc/openapi-router` 是围绕快递和Hono等网络框架的路由器的薄包装器,提供OpenAPI类型安全,并与Valibot和Zod等验证库进行无缝整合.

-   **类型安全**: 与 TypeScript 为强类型的安全而构建并支持 [`openapi-typescript`](https://github.com/drwpow/openapi-typescript) 类型
-   **框架不可知论**: 与Express,Hono等通俗网络框架相兼容
-   **第一次验证**: 与 Valibot, Zod 和其他验证器合并,以确保请求符合预期类型
-   **模块可扩展( L)**: 具有以下特征的易于扩展: `withExpress()`. . . . . . .

### 实例

-   [快递商店](https://github.com/builder-group/monorepo/tree/develop/examples/openapi-router/express/petstore)
-   [霍诺·彼得斯托尔](https://github.com/builder-group/monorepo/tree/develop/examples/openapi-router/hono/petstore)

### 动机

在网络框架路由器周围创建一个类型安全而直截了当的包装器,使用 OpenAPI 计划进行无缝整合 `openapi-typescript` 并确保与Zod和Valibot等图书馆进行类型验证.

## 使用量

### [快递Js](https://expressjs.com/)

[`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router) 环绕 [快速路由器](https://expressjs.com/en/5x/api.html#router) 实现完全类型安全,并使用验证器执行您的 OpenAPI-Schema.

> 虽然TypeScript类型确保了编译时间的安全,但它们不执行运行时间的计时验证. 对于运行时间合规,需要与Zod或Valibot等验证库相整合. 尽管您必须手动定义验证规则,但这些规则对于确保这些规则的正确定义是安全的.

```ts
import { createExpressOpenApiRouter } from '@blgc/openapi-router';
import { Router } from 'express';
import * as v from 'valibot';
import { vValidator } from 'validation-adapters/valibot';
import { paths } from './gen/v1'; // OpenAPI-generated types
import { PetSchema } from './schemas'; // Custom reusable Zod schema for validation

export const router: Router = Router();
export const openApiRouter = createExpressOpenApiRouter<paths>(router);

// GET /pet/{petId}
openApiRouter.get('/pet/{petId}', {
    pathValidator: vValidator(
        v.object({
            petId: v.number() // Validate that petId is a number
        })
    ),
    handler: (req, res) => {
        const { petId } = req.params; // Access validated params
        res.send({ name: 'Falko', photoUrls: [] });
    }
});

// POST /pet
openApiRouter.post('/pet', {
    bodyValidator: vValidator(PetSchema), // Validate request body using PetSchema
    handler: (req, res) => {
        const { name, photoUrls } = req.body; // Access validated body data
        res.send({ name, photoUrls });
    }
});
```

[完整实例](https://github.com/builder-group/community/tree/develop/examples/openapi-router/express/petstore)

### [浩诺](https://hono.dev/)

[`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router) 环绕 [Hono 路由器](https://hono.dev/docs/api/routing) 实现完全类型安全,并使用验证器执行您的 OpenAPI-Schema.

> 虽然TypeScript类型确保了编译时间的安全,但它们不执行运行时间的计时验证. 对于运行时间合规,需要与Zod或Valibot等验证库相整合. 尽管您必须手动定义验证规则,但这些规则对于确保这些规则的正确定义是安全的.

> Hono 类型脚本集成提供了类型建议 `c.json()` 基于通用定义的响应类型,但在编译时不强制执行这些类型. 譬如说, `c.json('')` 即使预期类型是,也不会产生类型错误 `{someType: string}`这是由于Hono内部使用 `TypedResponse<T>`,这可以推断,但不严格地执行所传通类. [霍诺讨论](https://github.com/orgs/honojs/discussions/3331)

```ts
import { createHonoOpenApiRouter } from '@blgc/openapi-router';
import { Hono } from 'hono';
import { zValidator } from 'validation-adapters/zod';
import * as z from 'zod';
import { paths } from './gen/v1'; // OpenAPI-generated types
import { PetSchema } from './schemas'; // Custom reusable Zod schema for validation

export const router = new Hono();
export const openApiRouter = createHonoOpenApiRouter<paths>(router);

// GET /pet/{petId}
openApiRouter.get('/pet/{petId}', {
    pathValidator: zValidator(
        z.object({
            petId: z.number() // Validate that petId is a number
        })
    ),
    handler: (c) => {
        const { petId } = c.req.valid('param'); // Access validated params
        return c.json({ name: 'Falko', photoUrls: [] });
    }
});

// POST /pet
openApiRouter.post('/pet', {
    bodyValidator: zValidator(PetSchema), // Validate request body using PetSchema
    handler: (c) => {
        const { name, photoUrls } = c.req.valid('json'); // Access validated body data
        return c.json({ name, photoUrls });
    }
});
```

[完整实例](https://github.com/builder-group/community/tree/develop/examples/openapi-router/hono/petstore)

## 常见问题

### @blgc/openapi-router 是什么？

紧绕快递和Hono等网络框架的路由器,提供OpenAPI类型安全和与Valibot和Zod等验证库的无缝整合注意：该包已被作者标记为弃用——Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

### 如何安装 @blgc/openapi-router？

在项目目录运行 npm install @blgc/openapi-router，或使用 pnpm add / yarn add / bun add。

### @blgc/openapi-router 支持 TypeScript 吗？

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

### @blgc/openapi-router 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @blgc/openapi-router 可以商用吗？

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

### @blgc/openapi-router 的下载量有多少？

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

### @blgc/openapi-router 还在维护吗？

最新版本 0\.1\.0 发布于 2024/12/22（1\.9 年前）；至今共发布 14 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/08/02。作者已将其标记为弃用，新项目建议寻找替代方案。