第一件事：为什么要在已经存在一个 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 规范以满足您项目的要求。
准备好开始了吗？
如果这听起来像是您一直在等待的解决方案，请查看库并加入对话：
我希望本文能够说服您尝试 hono-openapi 并了解它如何简化 api 的构建和文档记录。您的反馈很重要！让我们一起建立一个更强大的 honojs 社区。
