# APIを100%の一致でHuma v2へ移行

HTTP APIの649パス・760操作をFiberからHuma v2へ移行し、サーバーが登録するルートと公開するOpenAPI記述の100%一致を達成・維持した。

2025

**状況.** APIはFiberで始まり、エンドポイントごとにリクエスト検証を手書きしていた。少数ならよくても、増えるにつれ保守負担となり、各実装が独自であるため小さな不一致が入り込んだ。API全体の構造を表す単一の記述もなかった。

**課題.** 全面的な一括書き直しのために止まることなく、手書き検査の代わりに型から検証を生み、APIの構造を記述する仕様を得ることが目標だった。

**行動.** 既存ランタイムを保ち、Fiber上のHuma v2へHTTP層を移した。各エンドポイントに入力・出力構造体を設け、型からHumaが検証と応答モデルを生成する。OpenAPI記述も自動で得られ、wikiで古くなるのでなくコードに追随する。新規はすべてHumaで書き、既存も移行した。ただし、ソケット自体が必要でリクエスト・応答モデルに合わないWebSocketの2エンドポイントだけを、生のFiberに残した。規模は649パス・760操作となり、実際の登録ルートとOpenAPIが公表するルートをCIで比較する。未記述ルートがビルドを失敗させるため、一致率100%を維持する。

**結果.** 追加作業なしで新規エンドポイントに検証と最新文書が備わり、項目の検査忘れのようなリクエスト処理バグの一群がなくなった。760操作では、APIを読む実用的な手段は記述しかなく、完全性の保証は50操作だったころ以上に重要だった。型によって期待する入力を伝えるAPI仕様によって、安全に変更でき、人に引き継ぎやすいAPIとなった。

---

- 役割: バックエンドエンジニア
- カテゴリー: [プラットフォーム設計](https://advisory.engineer.company/ja/categories/platform-architecture/), [バックエンド開発](https://advisory.engineer.company/ja/categories/backend/), [API・システム連携](https://advisory.engineer.company/ja/categories/api/), [移行・モダナイゼーション](https://advisory.engineer.company/ja/categories/migration/), [テスト・品質保証](https://advisory.engineer.company/ja/categories/testing/), [文書作成](https://advisory.engineer.company/ja/categories/documentation/)
- サービス: [プラットフォーム・ソリューション設計](https://advisory.engineer.company/ja/services/platform-architecture/), [バックエンド・API開発](https://advisory.engineer.company/ja/services/backend-development/), [AIエージェント用ツール・MCPサーバー](https://advisory.engineer.company/ja/services/ai-tools/), [技術文書の作成](https://advisory.engineer.company/ja/services/technical-documentation/)

<https://engineer.company/ja/portfolio/migrated-the-api-to-huma-v2-at-100-parity/>
