第一件事：为什么要在已经存在一个 openapi 库的情况下为 hono 创建另一个 openapi 库？
这是很多人问过的问题。是的，有由 yusuke 创建的 zod openapi。虽然它是一个很棒的软件包，但它有一些重大的局限性，导致了新解决方案的创建。
@hono/zod-openapi 面临的挑战
让我们通过比较这两种方法来解释为什么要构建 hono-openapi。
1. 语法和工作流程差异这是使用 @hono/zod-openapi 的示例：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
// 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 编写的同一应用程序进行比较：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
// 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？
与验证器无关：使用您喜欢的验证库 - zod、typebox、arktype、valibot 或其他库。 无缝集成：将其作为中间件添加到任何 honojs 项目中，只需进行最少的更改。 自动 openapi 生成：定义一次架构，让库处理其余的事情。 类型安全：使用 typescript 构建，以实现可靠且一致的类型验证。 可定制：定制生成的 openapi 规范以满足您项目的要求。准备好开始了吗？
如果这听起来像是您一直在等待的解决方案，请查看库并加入对话：
github 存储库：hono-openapi 文档：github 自述文件 |荣誉示例我希望本文能够说服您尝试 hono-openapi 并了解它如何简化 api 的构建和文档记录。您的反馈很重要！让我们一起建立一个更强大的 honojs 社区。
以上就是Hono OpenAPI 简介：简化 HonoJS 的 API 文档的详细内容，更多请关注php中文网其它相关文章！