# @alxia/openapi 中文文档

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

版本：0\.6\.14
npm 元数据更新时间：2026-11-02T11:20:04.737Z
中文译文更新时间：2026-11-06T08:37:35.058Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40alxia/openapi
原文对照：https://npmcn.com/package/%40alxia/openapi/?lang=original
源码仓库：https://github.com/softistx/alxia

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

- 包体积（解压后）：123 kB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：typescript ^6\.0\.3 \|\| ^7\.0\.0，@alxia/core ^0\.19\.0
- 首次发布：2026-10-03T17:20:14.466Z
- 最新版本发布：2026-11-02T11:20:04.549Z
- 近 30 天下载量：3787（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

OpenAPI spec first for@alxia/core:一个应用的路径绑定在其文档生成的操作上,并对照它们检查

## 安装

```sh
npm install @alxia/openapi
```

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

## README

# @alxia/ openapi (英语)

第一个 OpenAPI 光谱 [`@alxia/core`](https://www.npmjs.com/package/@alxia/core)。 。 。 . OpenAPI 文档是源代码 : [`@nxgt/openapi-codegen`](https://www.npmjs.com/package/@nxgt/openapi-codegen)是因为 `alxia` 选项生成每个操作为 `{ method, path, schema }`, (中文(简体) ), `@alxia/core`是因为 `app.route(operation, ...middlewares, handler)` 绑定 a 这个包裹是 `implemented` 财务报告和审定财务报表 `matchesSpec` 检查 该应用程序将引导文档的每个操作(以及 `strict: true`只有这些。 文件声明的路由, 没有人写 测试失败,不是客户端.

```sh
bun add -d @alxia/openapi typescript
bun add -d --exact @nxgt/openapi-codegen
bun add zod
```

`@alxia/core` 财务报告和审定财务报表 `typescript` 是同龄人; `@alxia/core` 是应用程序的 自己的依赖. `@nxgt/openapi-codegen` 写入操作和代码 它写入导入 `zod` (4.5.4或后)运行时间。 启动时检查 而不是在测试中,安装 `@alxia/openapi` 无 `-d`。 。 。 .

`bun create @alxia my-api --template api` 启动此方式的工程 .

## 斯佩克第一,结束到结束

写入 `openapi.yaml` - 这里有一个 `listTodos` (单位:千美元) `createTodo` 操作——然后指向它:

```ts
// openapi-codegen.config.ts
import { defineConfig } from '@nxgt/openapi-codegen';

export default defineConfig({
    input: 'openapi.yaml',
    output: 'src/generated',
    alxia: true, // writes src/generated/alxia.ts
    validationErrors: false, // alxia sends its own 400: declare it in the spec
});
```

```sh
bunx nxgt-openapi generate # writes src/generated/, alxia.ts included
```

将每个操作与它的处理器结合,并配有它所需要的中间器件:

```ts
// src/app.ts
import { alxia, defineMiddleware } from '@alxia/core';
import { operations } from './generated/alxia';
import type { Todo } from './generated/types';

const requireKey = defineMiddleware(({ request, reply }, next) =>
    request.headers.get('x-api-key') === Bun.env['API_KEY']
        ? next()
        : reply(401, { error: 'unauthorized' as const }),
);

const todos: Todo[] = [];

export const app = alxia()
    .route(operations.listTodos, ({ reply }) => reply.ok(todos))
    .route(operations.createTodo, requireKey, ({ body, reply }) => {
        const todo = { id: todos.length + 1, title: body.title, done: false };
        todos.push(todo);
        return reply.created(todo);
    });
```

并对照相同的操作检查应用程序:

```ts
// src/app.spec.ts
import { test } from 'bun:test';
import { matchesSpec } from '@alxia/openapi';
import { app } from './app';
import { operations } from './generated/alxia';

test('routes every operation of openapi.yaml', () => {
    matchesSpec(app, operations);
});
```

这个 [光谱第一指南](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/guide/spec-first.md) 每一步都走一遍:文件,alxia自己的400个中间器皿, 执行生成的文件,以及同一文档中的客户端.

## API 文件

`apiDocs` 提供文档和一个交互式页面,没有 配置 。 页面从CDN装入,带有被绑定的版本和 子资源完整性散列,所以不增加您的依赖.

```ts
import { alxia } from '@alxia/core';
import { apiDocs } from '@alxia/openapi';
import spec from '../openapi.yaml'; // Bun imports YAML, and bundles it

const app = alxia().plugin(apiDocs({ spec }));
// GET /docs                  the page (Scalar)
// GET /docs/openapi.yaml     the document
// GET /docs/openapi.json     the same, as JSON
```

`spec` 是作为对象的文档——如上所导入,所以 `bun build` 捆绑它和一幅图像 `dist/` 单枪匹马仍然为它服务,或 路径到 YAML 或 JSON 文件,从工作开始一次读取 目录。 选项 : `path` (单位:千美元)`/docs`, (中文(简体) ), `ui` (单位:千美元)`'scalar'` 或者说 `'swagger'`, (中文(简体) ), `title`, (中文(简体) ), `servers` (取代文件的)和 `enabled`。该文件是 公开的,除非你守护着它:在发展过程中只服务于它 运行时环境 `Bun.env` —— 说 `apiDocs({ spec, enabled: Bun.env.NODE_ENV === 'development' })` —— 说 永远 `process.env.NODE_ENV`,哪个 `bun build` 替换为模式 建筑; 保持它后面的登录, 给警卫 `use('/docs', …)` 在插件之前。 页面设置自己的 `Content-Security-Policy`,哪个 `secureHeaders` 保留,以及 `matchesSpec` 离开它的路线。 这个 [指南](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/guide/api-docs.md) 有选择权 保险单 被保护的页面 还有 `apiDocs` 在图QL旁 终点.

## 每个行动都有一条路线

```ts
import { implemented } from '@alxia/openapi';

implemented(app, operations); // routes the app serves beside the spec are fine
```

当缺少一些时,它抛出,按方法,路径和操作代号分别命名:

```text
TypeError: implemented(): 2 operations have no route: GET /pets/:petId (getPet), QUERY /employees (searchEmployees)
```

## 只有行动

```ts
import { matchesSpec } from '@alxia/openapi';

const { extra } = matchesSpec(app, operations);
```

`matchesSpec` 抛出为 `implemented` 是:在无路线的每次行动中, 在另一种方法或路径的路线上 未宣布操作的路由 (代理者、健康检查、手写者)不会失败 返回为 `extra`, (中文(简体) ), `[{ method, path }]`,所以测试可以断言。 一个 `app.all(path, …)` 路由不服务,并列为 `{ method: 'ALL', path }`。 。 。 .

对于必须详尽无遗的规格,请通过 `strict: true`: 每条路线无 操作也宣告失败, `exclude` 让开 路线 `apiDocs()` 和探测器 `@alxia/core`是因为 `health()` 已忽略 :

```ts
matchesSpec(app, operations, {
    strict: true,
    exclude: (route) => route.path === '/metrics',
});
```

```text
TypeError: matchesSpec(): 1 operation has no route: GET /pets/:petId (getPet); 1 route has no operation: POST /admin/reset
```

从此检查宽大之前升级: 保存旧的检查, 通过 `strict: true`。 。 。 .

## 在前缀下

```ts
implemented(app, operations, { prefix: '/api' });
```

有关前缀和路线匹配的详情,见 [匹配 md 数据](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/guide/matching.md#under-a-prefix)。检查内容为 `app.routes` 他们没有要求,也没有检查任何计划.

## 有中间软件的路由

`app.route(operation, ...middlewares, handler)` 验证请求并 请检查date=中的日期值 (帮助) `validate(operation)` 财务报告和审定财务报表 `responds(operation)` 站起来 中间器件的自有 答复,例如一个Author的401,是按原样发送的. 支票就跟这一样 路径:

```ts
import { alxia, validate } from '@alxia/core';
import { operations } from './generated/alxia';

// requireKey, todos: as above
export const app = alxia()
    .route(operations.listTodos, ({ reply }) => reply.ok(todos))
    .route(
        operations.createTodo,
        requireKey, // first: an anonymous client gets its 401 before the body is read
        validate(operations.createTodo),
        ({ body, reply }) => reply.created({ id: todos.length + 1, title: body.title, done: false }),
    );
```

将密钥检查放在前面 `validate(...)`: 认证先行, 所以匿名客户端 没有身体解剖,直到 `bodyLimit`中,没有验证问题,哪个 将揭示计划.

## 陷阱

-   `validationErrors` 默认为 `true`,在客户端中声明 400 alxia 从未发送文件: set `validationErrors: false` 并宣布 爱克夏 `{ error: 'validation', issues }` 在谱中.
-   发电机不转 `security` 输入中间软件:用 `defineMiddleware` 并把它给 `route(operation, auth, handler)`。 。 。 .
-   单位 `@nxgt/openapi-codegen` 0.11.0, a (单位:千美元) `cookie` 参数被验证为 `cookies` 以 `alxia.ts` 单独: 客户端文件将它留出 `ignored` 警告,因为客户端没有设置 cookie 。 一个饼干,这是一个 列表或对象失败运行.

## 来自 `@alxia/openapi` 0.3 或 减值 `@alxia/openapi-routes`

**`@alxia/openapi` 0.1至0.3 (韩语)** 是另一个软件包: 它写了一个文档 从应用程序的路线( )`openapi`, (中文(简体) ), `docs`, (中文(简体) ), `toJsonSchema`) (中文(简体) ). 已经退休了, 由于该文件现在首先提出,0.4没有出口。 保存 它提供的文件,应用程序 `/openapi.json`,作为起点 生成 : 并用它来约束航道 `app.route()`。 。 。 .

**`@alxia/openapi-routes`** 之前名下的这个包裹,现在 从存储器中删除。 移动到 `@alxia/openapi`: 不变 函数、选项和消息,但 `exactly` 财务报告和审定财务报表 `ExactlyOptions`, (中文(简体) ), 其贬值的别名: `matchesSpec` 财务报告和审定财务报表 `MatchesSpecOptions`不见了 在0.5时.

```sh
bun remove @alxia/openapi-routes
bun add -d @alxia/openapi
```

```ts
// before
import { implemented, matchesSpec } from '@alxia/openapi-routes';
// after
import { implemented, matchesSpec } from '@alxia/openapi';
```

核心的一面 移动在它的 [升级说明](https://github.com/softistx/alxia/blob/develop/packages/core/docs/upgrading.md#no-more-client-spec-first)。 。 。 .

## API 密码

| 导出 |  |
| --- | --- |
| `implemented(app, operations, options?)`, (中文(简体) ), `ImplementedOptions` | 丢出一个 `TypeError` 列出没有路由的每个操作,或者有核心操作路径原因的操作,无法声明路由. `prefix` |
| `matchesSpec(app, operations, options?)`, (中文(简体) ), `MatchesSpecOptions`, (中文(简体) ), `MatchesSpecReport` | 返回时 `{ extra }`未申报的路线; `apiDocs()`还有.. `@alxia/core`是因为 `health()` 抛出探测器; 下 `strict: true` 剩下的就扔出来. `prefix`, (中文(简体) ), `strict`, (中文(简体) ), `exclude` |
| `apiDocs(options)`, (中文(简体) ), `ApiDocsOptions`, (中文(简体) ), `DocsUi`, (中文(简体) ), `DocsServer` | 插件: 页面 `path`,文档在 `path/openapi.yaml` 财务报告和审定财务报表 `.json`。 。 。 . `spec`, (中文(简体) ), `path`, (中文(简体) ), `ui`, (中文(简体) ), `title`, (中文(简体) ), `servers`, (中文(简体) ), `enabled` |
| `isApiDocsRoute(route)` | 是否为 `apiDocs` 已声明路径, 任何 `{ handler }` (单位:千美元)`Pick<RouteDefinition, 'handler'>`作为核心 `isHealthRoute`(三); `matchesSpec` 别管他们了 |
| `Operations` | 两者都取: 核心的物体 `RouteOperation`,或列表中 |

## 文档

-   [文件索引](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/README.md):每一页,何时读取.
-   [斯贝克先](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/guide/spec-first.md): 整个工作流程,来自 `openapi.yaml` 到生成的操作,路径,检查和客户端.
-   [用生成的客户端进行测试](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/guide/testing.md)数字 : `@nxgt/openapi-httpyz` 结束 `app.fetch`,在进程中,由 spec 键入.
-   [API 文件](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/guide/api-docs.md)数字 : `apiDocs`,其选项,内容-安全政策,以及GraphQL端点.
-   [检查](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/guide/checks.md)数字 : `implemented` 财务报告和审定财务报表 `matchesSpec`和排除的路线.
-   [路线如何匹配](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/guide/matching.md):路径的形状,前缀和特例.
-   [解决问题](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/troubleshooting.md):检查和生成器的每条信息,以及该如何处理.
-   [路线图](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/roadmap.md):即将到来的,以及没有计划的.
-   [食谱](https://github.com/softistx/alxia/blob/develop/docs/recipes/README.md)数字 : [光谱第一 CRUD API](https://github.com/softistx/alxia/blob/develop/docs/recipes/spec-first-crud.md), (中文(简体) ), [测试 alxia 应用程序](https://github.com/softistx/alxia/blob/develop/docs/recipes/testing.md), (中文(简体) ), [持续回答错误](https://github.com/softistx/alxia/blob/develop/docs/recipes/errors.md)。 。 。 .

## 常见问题

### @alxia/openapi 是什么？

OpenAPI spec first for@alxia/core:一个应用的路径绑定在其文档生成的操作上,并对照它们检查

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

在项目目录运行 npm install @alxia/openapi，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typescript（^6\.0\.3 \|\| ^7\.0\.0）、@alxia/core（^0\.19\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

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

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

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

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

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