Hono OpenAPI の紹介: HonoJS の API ドキュメントの簡素化

まず最初に: Hono 用の OpenAPI ライブラリがすでに存在するのに、なぜ別の OpenAPI ライブラリを作成するのでしょうか?

これは多くの人から寄せられた質問です。はい、Yuuke が作成した Zod OpenAPI があります。これは優れたパッケージですが、新しいソリューションの作成につながる重大な制限がいくつかあります。

@hono/zod-openapi の課題

2 つのアプローチを比較することで、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 は次の目標を念頭に置いて構築されました。

• Validator-Agnostic: 好みの検証ライブラリ (Zod、Typebox、ArkType、Valibot など) を使用します。
• シームレスな統合: 最小限の変更で、ミドルウェアとして HonoJS プロジェクトに追加します。
• OpenAPI の自動生成: スキーマを一度定義すれば、残りはライブラリに処理させます。
• タイプセーフ: 信頼性と一貫性のある型検証のために TypeScript で構築されています。
• カスタマイズ可能: 生成された OpenAPI 仕様をプロジェクトの要件に合わせて調整します。

---

始める準備はできましたか?

これがあなたが待ち望んでいた解決策のように思われる場合は、ライブラリをチェックして会話に参加してください:

• GitHub リポジトリ: hono-openapi
• ドキュメント: GitHub README |ほのの例

---

この記事を読んで、hono-openapi を試してみて、API の構築と文書化がどのように簡素化されるかを理解していただければ幸いです。あなたのフィードバックは重要です!一緒に強力な HonoJS コミュニティを構築しましょう。

以上がHono OpenAPI の紹介: HonoJS の API ドキュメントの簡素化の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。