Hono OpenAPI 简介：简化 HonoJS 的 API 文档

首先要做的事情：为什么要在已经存在一个 OpenAPI 库的情况下为 Hono 创建另一个库？

这是很多人问过的问题。是的，有由 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 规范会改变游戏规则：

1. API客户端生成：使用规范自动生成各种编程语言的客户端，节省开发时间。
2. 开发人员协作：让您的团队与最新的 API 文档保持同步，减少沟通不畅和错误。
3. 简化调试：通过为所有端点提供清晰、准确的文档，消除 API 失败时的猜测。
4. 最佳实践：自动生成随代码库一起发展的文档，确保跨分支和版本的一致性。

如果您曾经在前端和后端开发人员必须手动同步 API 详细信息的团队工作过，您就会知道这有多痛苦。 OpenAPI 规范通过提供单一事实来源解决了这个问题。

---

为什么选择hono-openapi？

为了应对这些挑战并推广最佳实践，hono-openapi 的构建考虑了以下目标：

• 与验证器无关：使用您喜欢的验证库 - Zod、Typebox、ArkType、Valibot 或其他库。
• 无缝集成：将其作为中间件添加到任何 HonoJS 项目中，只需进行最少的更改。
• 自动 OpenAPI 生成：定义一次架构，让库处理其余的事情。
• 类型安全：使用 TypeScript 构建，以实现可靠且一致的类型验证。
• 可定制：定制生成的 OpenAPI 规范以满足您项目的要求。

---

准备好开始了吗？

如果这听起来像是您一直在等待的解决方案，请查看库并加入对话：

• GitHub 存储库：hono-openapi
• 文档：GitHub 自述文件 |荣誉示例

---

我希望本文能够说服您尝试 hono-openapi 并了解它如何简化 API 的构建和文档记录。您的反馈很重要！让我们一起建立一个更强大的 HonoJS 社区。

以上是Hono OpenAPI 简介：简化 HonoJS 的 API 文档的详细内容。更多信息请关注PHP中文网其他相关文章！