{"canonical_url":"https://engineer.company/ja/portfolio/migrated-the-api-to-huma-v2-at-100-parity/","content_markdown":"# APIを100%の一致でHuma v2へ移行\n\nHTTP APIの649パス・760操作をFiberからHuma v2へ移行し、サーバーが登録するルートと公開するOpenAPI記述の100%一致を達成・維持した。\n\n2025\n\n**状況.** APIはFiberで始まり、エンドポイントごとにリクエスト検証を手書きしていた。少数ならよくても、増えるにつれ保守負担となり、各実装が独自であるため小さな不一致が入り込んだ。API全体の構造を表す単一の記述もなかった。\n\n**課題.** 全面的な一括書き直しのために止まることなく、手書き検査の代わりに型から検証を生み、APIの構造を記述する仕様を得ることが目標だった。\n\n**行動.** 既存ランタイムを保ち、Fiber上のHuma v2へHTTP層を移した。各エンドポイントに入力・出力構造体を設け、型からHumaが検証と応答モデルを生成する。OpenAPI記述も自動で得られ、wikiで古くなるのでなくコードに追随する。新規はすべてHumaで書き、既存も移行した。ただし、ソケット自体が必要でリクエスト・応答モデルに合わないWebSocketの2エンドポイントだけを、生のFiberに残した。規模は649パス・760操作となり、実際の登録ルートとOpenAPIが公表するルートをCIで比較する。未記述ルートがビルドを失敗させるため、一致率100%を維持する。\n\n**結果.** 追加作業なしで新規エンドポイントに検証と最新文書が備わり、項目の検査忘れのようなリクエスト処理バグの一群がなくなった。760操作では、APIを読む実用的な手段は記述しかなく、完全性の保証は50操作だったころ以上に重要だった。型によって期待する入力を伝えるAPI仕様によって、安全に変更でき、人に引き継ぎやすいAPIとなった。\n\n---\n\n- 役割: バックエンドエンジニア\n- カテゴリー: [プラットフォーム設計](https://software.engineer.company/ja/categories/platform-architecture/), [バックエンド開発](https://software.engineer.company/ja/categories/backend/), [API・システム連携](https://software.engineer.company/ja/categories/api/), [移行・モダナイゼーション](https://software.engineer.company/ja/categories/migration/), [テスト・品質保証](https://software.engineer.company/ja/categories/testing/), [文書作成](https://software.engineer.company/ja/categories/documentation/)\n- サービス: [プラットフォーム・ソリューション設計](https://software.engineer.company/ja/services/platform-architecture/), [バックエンド・API開発](https://software.engineer.company/ja/services/backend-development/), [AIエージェント用ツール・MCPサーバー](https://software.engineer.company/ja/services/ai-tools/), [技術文書の作成](https://software.engineer.company/ja/services/technical-documentation/)\n\n\u003chttps://engineer.company/ja/portfolio/migrated-the-api-to-huma-v2-at-100-parity/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"649パス・760操作のHTTP APIをFiberからHuma v2へ移行し、登録ルートと公開OpenAPI記述を100%一致させた。","formats":{"gemtext":"https://software.engineer.company/ja/portfolio/migrated-the-api-to-huma-v2-at-100-parity/index.gmi","gopher":"https://software.engineer.company/ja/portfolio/migrated-the-api-to-huma-v2-at-100-parity/gophermap","html":"https://software.engineer.company/ja/portfolio/migrated-the-api-to-huma-v2-at-100-parity/","json":"https://software.engineer.company/ja/portfolio/migrated-the-api-to-huma-v2-at-100-parity/index.json","markdown":"https://software.engineer.company/ja/portfolio/migrated-the-api-to-huma-v2-at-100-parity/index.md","pdf":"https://software.engineer.company/ja/portfolio/migrated-the-api-to-huma-v2-at-100-parity/index.pdf"},"kind":"page","language":"ja","title":"APIを100%の一致でHuma v2へ移行","url":"https://software.engineer.company/ja/portfolio/migrated-the-api-to-huma-v2-at-100-parity/","version":1}