Hono OpenAPI 使用教程

Hono OpenAPI 使用教程

hono-openapi A plugin for Hono to generate OpenAPI Swagger documentation 项目地址: https://gitcode.com/gh_mirrors/ho/hono-openapi

1. 项目介绍

Hono OpenAPI 是一个开源插件，用于为 Hono API 自动生成 OpenAPI 规范。通过使用您的验证模式，它可以生成客户端库、文档等。Hono OpenAPI 支持多种验证库，包括 Zod、Valibot、ArkType、TypeBox 和 Effect。

2. 项目快速启动

以下是快速启动 Hono OpenAPI 的步骤：

首先，您需要安装 Node.js 环境。然后，使用以下命令安装必要的依赖：

pnpm add hono-openapi @hono/zod-validator zod zod-openapi

接下来，定义您的验证模式。以下是一个使用 Zod 的示例：

import { z } from 'zod';
import 'zod-openapi/extend';

const querySchema = z.object({
  name: z.string().optional().openapi({ example: "Steven" }),
}).openapi({ ref: "Query" });

const responseSchema = z.string().openapi({ example: "Hello Steven!" });

之后，创建您的路由：

import { Hono } from 'hono';
import { describeRoute } from 'hono-openapi';
import { resolver, validator as zValidator } from 'hono-openapi/zod';

const app = new Hono();

app.get('/', describeRoute({
  description: "Say hello to the user",
  responses: {
    200: {
      description: "Successful greeting response",
      content: {
        'text/plain': {
          schema: resolver(responseSchema),
        },
      },
    },
  },
}), zValidator('query', querySchema), (c) => {
  const query = c.req.valid('query');
  return c.text(`Hello ${query?.name ?? "Hono"}!`);
});

最后，生成 OpenAPI 规范：

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",
      },
    ],
  },
}));

现在，您可以通过访问 http://localhost:3000/openapi 来查看生成的 OpenAPI 规范。

3. 应用案例和最佳实践

• 添加安全定义：您可以通过在 openAPISpecs 函数中使用 security 属性来为您的 OpenAPI 规范添加安全定义。
• 条件隐藏路由：您可以使用 describeRoute 函数中的 hide 属性来根据环境变量条件隐藏路由。
• 验证响应：您可以通过在 describeRoute 函数中使用 validateResponse 属性来验证响应的有效性。

4. 典型生态项目

Hono OpenAPI 可以与多种开源项目配合使用，例如 Swagger UI 和 Scalar，这些工具可以帮助您生成文档和客户端库。以下是一个使用 Swagger UI 展示 API 文档的示例：

app.get('/docs', apiReference({
  theme: 'saturn',
  spec: {
    url: '/openapi',
  },
}));

以上就是 Hono OpenAPI 的使用教程，希望对您有所帮助。

hono-openapi A plugin for Hono to generate OpenAPI Swagger documentation 项目地址: https://gitcode.com/gh_mirrors/ho/hono-openapi