标签导航：

hono openapi 简介：简化 honojs 的 api 文档

第一件事：为什么要在已经存在一个 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 规范会改变游戏规则：

  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 社区。