バックエンドのコードファーストなOpenAPIスキーマ駆動開発 - TSKaigi2025

スポンサーLT

バックエンドの実装からOpenAPIを自動生成し、そのスキーマを使ってフロントエンドまで型安全に連携する取り組みをご紹介します。
コードファーストで始めることで、ドキュメントとのズレをなくし、開発効率と品質の両立を目指しました。

Transcript

1. バックエンドのコードファーストな OpenAPIスキーマ駆動開発 KINTOテクノロジーズ株式会社 2025/05/24 TSKaigi 2025
2. ©KINTO Corporation. All rights reserved. 2 プロフィール 共通サービス開発グループでは、KINTO会員基盤のフロントエンド 開発（TypeScript, Next.js）を担当。 AI開発グループでは、生成AIを活用したプロダクト開発でフロント エンド（TypeScript）バックエンド（TypeScript, Go, Python）、 インフラを幅広く担当しています。 最近はmastraを利用したプロダクトに興味があります。 MastraはオープンソースのTypeScript AIエージェントフレームワークです。 https://mastra.ai/ KINTOテクノロジーズ株式会社 共通サービス開発グループ / AI開発グループ Web Application Engineer 鳥居 雄仁 x: @yu_torii
3. ©KINTO Corporation. All rights reserved. 3 KINTOテクノロジーズ株式会社について（グループ組織） トヨタ自動車株式会社 トヨタファイナンシャルサービス株式会社（TFS） 海外販売金融 現地事業会社 世界40以上の国と地域で サービスを展開 KINTOテクノロジーズ 株式会社 株式会社KINTO トヨタファイナンス 株式会社 販売金融・クレジット カードなど
4. ©KINTO Corporation. All rights reserved. 4 KINTOテクノロジーズが関わっているプロダクト
5. ©KINTO Corporation. All rights reserved. 5 アジェンダ 1. よくある課題と背景 2. OpenAPI管理の難しさ 3. コードファーストな解決方法 4. 型生成の具体的フロー - 4-1. 全体フロー概要 - 4-2. Makefileで自動化 - 4-3. Makefileの中身とポイント 5. フロントエンドでの統合 6. 導入して見えた利点と課題 7. 代替ツールと今後の改善案 8. まとめ
6. ©KINTO Corporation. All rights reserved. 6 1. よくある課題と背景 - API変更をフロントに伝え忘れてクラッシュ - enumのtypoでロジックが壊れる - requiredやnullable設定ミスで想定外の挙動 - OpenAPIドキュメントが常に古く信頼されない 理想はこれ↓ 実装変更 → スキーマ自動更新 → フロント型同期（完全自動） クラッシュの例： パラメータ変更に追従していない
7. ©KINTO Corporation. All rights reserved. 7 2. OpenAPI管理の難しさ - 設計が複雑でルールが多い（リソース設計、命名、バー ジョニングなど） - コード補完が弱い(プログラミング言語に比べ） - YAMLが肥大化・複雑化して、管理が難しい - ファイル分割や$refの多用で混乱が起きやすい だからこそ、コードファーストで自動化したい スキーマ駆動開発といえば、 一般的には OpenAPI.yml を起点に書いていくアプローチ
8. ©KINTO Corporation. All rights reserved. 8 3. コードファーストな解決方法 - バックエンドは元々Goを使用中だったので、 コードからOpenAPIを簡単に生成できるHumaを採用 - 他言語の代表的なライブラリ： - Python → FastAPI (型アノテーションから生成) - TypeScript → NestJS → Hono + OpenAPIプラグイン (RPCという選択肢も) 重要なのは「コードを起点にしてスキーマを自動生成すること」
9. ©KINTO Corporation. All rights reserved. 9 4-1. 型生成のフロー（概要） - バックエンド変更でOpenAPIスキーマを自動更新 - スキーマからZodスキーマ & Zodios クライアントのコードを Makefile経由で手動生成 （将来的に自動化予定） -フロントエンドは生成された型を使って型安全な実装が可能に
10. ©KINTO Corporation. All rights reserved. 10 4-2. Makefileによる型生成の自動化 - MakefileでZodスキーマとAPIクライアントを生成 - openapi-zod-client + Handlebarsテンプレートで柔軟に出力内 容を制御 - Zodスキーマ定義API - クライアント定義 - 公式テンプレートをベースにカスタマイズ
11. ©KINTO Corporation. All rights reserved. 11 4-3. Makefileの中身とポイント - curl で最新のスキーマを取得 - openapi-zod-client に渡して型・クライアントを 生成 - sed などで軽く整形処理（必要に応じて） - 一時ファイルを削除して終了
12. ©KINTO Corporation. All rights reserved. 12 5.フロントでの型安全な活用 - 自動生成された Zodスキーマで入力・出力のバリデーションを実現 - Zodiosを使って、型付きのAPIクライアントをそのまま呼び出し可能 - 型・バリデーションの手書きが不要に
13. ©KINTO Corporation. All rights reserved. 13 6. 導入して見えた利点と課題 – メリット 導入後のメリット OpenAPI.yml の手動管理からの解放 圧倒的に楽になったAPI実装 - 型定義・クライアントコードを手書きしなくて済む - 実装のスピードと正確性が向上 型ズレの早期発見 - バックエンドの型変更にビルドエラーで即気づける - 手戻りや見落としが激減 一方、見えてきた課題も →
14. ©KINTO Corporation. All rights reserved. 14 6. 導入して見えた利点と課題 – 課題 一方、見えてきた課題 ライブラリの継続性に不安 使用中の Zodios の更新が停滞気味 手動運用のリスク 型生成は Makefileで手動実行 → 実行忘れによる同期ミスの可能性
15. ©KINTO Corporation. All rights reserved. 15 7. 代替ツールと今後の改善案 代替ツールの選択肢 - Orval - OpenAPI から Zod スキーマ、Fetch、 TanStack Query、SWRコードから、MSW のモックなど様々なコード を自動生成 -バックエンドは現状のままで導入できる - Hono RPC - 新規構築時に有効な選択肢 - OpenAPI なしで RPC ベースのシンプルな型共有を実現
16. ©KINTO Corporation. All rights reserved. 16 7. 代替ツールと今後の改善案 今後の改善ポイント - GitHub Actions による型生成の自動化を検討中 - 現在はMakefileを手動で実行しており、 実行忘れ・タイミングのズレが起きる可能性がある - CIに組み込むことで、常に最新の型を維持しやすくなる
17. ©KINTO Corporation. All rights reserved. 17 8. まとめ - OpenAPI定義の手書きをやめ、コードから自動生成 へ - フロントエンドと型を共有し、型安全な実装が可能に - 仕様変更もビルドで即検知できる安心感 - CI連携などで、さらなる自動化・改善を目指す
18. ©KINTO Corporation. All rights reserved. 18 参考資料 •Huma (Go) https://github.com/danielgtaylor/huma •openapi-zod-client https://github.com/astahmer/openapi-zod-client • Handlebars テンプレート参考 ├ default.hbs https://github.com/astahmer/openapi-zod- client/blob/192da9c/lib/src/templates/default.hbs#L20 └ schemas-and-types-directly.hbs https://github.com/astahmer/openapi-zod- client/blob/192da9c/examples/export-schemas-and-types- directly/schemas-and-types-directly.hbs#L6
19. ©KINTO Corporation. All rights reserved. 19 参考資料 •Zod https://github.com/colinhacks/zod •Zodios https://github.com/ecyrbe/zodios •orval https://orval.dev • Zod連携ガイド https://orval.dev/guides/zod https://orval.dev/guides/client-with-zod
20. ©KINTO Corporation. All rights reserved. 20 参考資料 •Hono (TypeScript) https://hono.dev • OpenAPI Plugin https://github.com/honojs/openapi • RPC Example https://github.com/honojs/examples/tree/main/rpc •FastAPI (Python) https://fastapi.tiangolo.com •NestJS Swagger (Node.js) https://docs.nestjs.com/openapi/introduction
21. Thank you !