第一件事：为什么要在已经存在一个 openapi 库的情况下为 hono 创建另一个 openapi 库？
这是很多人问过的问题。是的，有由 yusuke 创建的 zod openapi。虽然它是一个很棒的软件包，但它有一些重大的局限性，导致了新解决方案的创建。
@hono/zod-openapi 面临的挑战
让我们通过比较这两种方法来解释为什么要构建 hono-openapi。
1. 语法和工作流程差异
这是使用 @hono/zod-openapi 的示例：
// using @hono/zod-openapi
import { openapihono, createroute, z } from '@hono/zod-openapi';
const paramsschema = z.object({
id: z
.string()
.min(3)
.openapi({
param: {
name: 'id',
in: 'path',
},
example: '1212121',
}),
});
const route = createroute({
method: 'get',
path: '/users/{id}',
request: {
params: paramsschema,
},
});
const app = new openapihono();
app.openapi(route, (c) => {
const { id } = c.req.valid('param');
return c.json({ id, age: 20, name: 'ultra-man' });
});
// the openapi documentation will be available at /doc
app.doc('/doc', {
openapi: '3.0.0',
info: {
version: '1.0.0',
title: 'my api',
},
});
现在将其与使用 hono-openapi 编写的同一应用程序进行比较：
// Using Hono-OpenAPI
import z from 'zod';
import { Hono } from 'hono';
import { describeRoute } from 'hono-openapi';
import { resolver, validator as zValidator } from 'hono-openapi/zod';
// Extending the Zod schema with OpenAPI properties
import 'zod-openapi/extend';
const paramSchema = z.object({
id: z.string().min(3).openapi({ example: '1212121' }),
});
const app = new Hono();
app.get(
'/',
zValidator('param', paramSchema),
(c) => {
const param = c.req.valid('param');
return c.text(`Hello ${param?.id}!`);
}
);
app.get(
'/openapi',
openAPISpecs(app, {
documentation: {
info: {
title: 'Hono',
version: '1.0.0',
description: 'API for greeting users',
},
servers: [
{ url: 'http://localhost:3000', description: 'Local server' },
],
},
})
);
区别很明显：hono-openapi 让您可以直接在标准 honojs 工作流程中工作。这消除了陡峭的学习曲线，并确保语法与 honojs 文档和约定保持一致。
2. 选择加入的挑战
使用 @hono/zod-openapi，改造现有的 honojs 应用程序以生成 openapi 规范是一项重大挑战。为大型应用程序重写路由可能非常耗时且容易出错。 hono-openapi 通过作为中间件来解决这个问题，因此您可以将其添加到现有应用程序中，而无需进行重大更改。
3. 验证者支持有限
原库仅支持zod。虽然 zod 非常出色，但许多开发人员使用 valibot、arktype 和 typebox 等替代品。 hono-openapi 与验证器无关，为多个库提供一流的支持。
为什么 openapi 规范很重要
有些人可能会想，“为什么要费心 openapi 规范呢？没有它们我的应用程序也能正常工作。”
这就是为什么生成 openapi 规范会改变游戏规则：
- api客户端生成：使用规范自动生成各种编程语言的客户端，节省开发时间。
- 开发人员协作：让您的团队与最新的 api 文档保持同步，减少沟通不畅和错误。
- 简化调试：通过为所有端点提供清晰、准确的文档，消除 api 失败时的猜测。
- 最佳实践：自动生成随代码库一起发展的文档，确保跨分支和版本的一致性。
如果您曾经在前端和后端开发人员必须手动同步 api 详细信息的团队工作过，您就会知道这有多痛苦。 openapi 规范通过提供单一事实来源解决了这个问题。
为什么选择hono-openapi？
为了应对这些挑战并推广最佳实践，hono-openapi 的构建考虑了以下目标：
- 与验证器无关：使用您喜欢的验证库 - zod、typebox、arktype、valibot 或其他库。
- 无缝集成：将其作为中间件添加到任何 honojs 项目中，只需进行最少的更改。
- 自动 openapi 生成：定义一次架构，让库处理其余的事情。
- 类型安全：使用 typescript 构建，以实现可靠且一致的类型验证。
- 可定制：定制生成的 openapi 规范以满足您项目的要求。
准备好开始了吗？
如果这听起来像是您一直在等待的解决方案，请查看库并加入对话：
- github 存储库：hono-openapi
- 文档：github 自述文件 |荣誉示例
我希望本文能够说服您尝试 hono-openapi 并了解它如何简化 api 的构建和文档记录。您的反馈很重要！让我们一起建立一个更强大的 honojs 社区。
