@alxia/ openapi (英语)

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

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 操作——然后指向它:

// 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
});

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

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

// 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);
    });

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

// 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);
});

这个 光谱第一指南 每一步都走一遍:文件,alxia自己的400个中间器皿, 执行生成的文件,以及同一文档中的客户端.

API 文件

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

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 离开它的路线。 这个 指南 有选择权 保险单 被保护的页面 还有 apiDocs 在图QL旁 终点.

每个行动都有一条路线

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

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

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

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

只有行动

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() 已忽略 :

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

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

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

在前缀下

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

有关前缀和路线匹配的详情,见 匹配 md 数据。检查内容为 app.routes 他们没有要求,也没有检查任何计划.

有中间软件的路由

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

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时.

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

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

核心的一面 移动在它的 升级说明。 。 。 .

API 密码

文档

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