うわっ...私のSwagger、古すぎ...？grpc-gateway向けのSwaggerと向き合う

フロントエンドカンファレンス関西2025 学生支援スポンサーイベントで行ったLTの資料です。

Transcript

1. うわっ...私のSwagger、古すぎ...？ grpc-gateway向けのSwaggerと 向き合う 2025/11/29 did0es
2. 自己紹介 did0es(🗣 ディドス) - Hirai shuta 株式会社サイバーエージェント グループIT推進本部 CIU Software Engineer(Web FrontEnd) Next Experts(TypeScript) Lead organizer for FEC Tokyo, Meguro.es X: https://x.com/did0es GitHub: https://github.com/shuta13 For more: https://did0.es
3. CIUのWeb開発の API定義(.protoファイル)から APIクライアントを 生成する仕組みの裏側について お話します
4. 1.CIU Webフロントの技術構成の紹介 2.Cycloud APIsについて 3.APIクライアントを自動生成する 4.自動生成で発生した問題に向き合う 5.まとめ
5. CIU Webフロントの 技術構成の紹介
6. やっていること： Cycloud(プライベートクラウド)の マネージドサービスのWebUI開発
7. 採用技術 以下をベースとして、 CIU Webフロントチームで内製している SDKを使用 • フレームワーク、ライブラリ Next.js(App Router)・React • スタイリング Tailwind CSS・UIライブラリ(Cloudscape, daisyUI, MUI, HeroUI etc…) • 開発ツール TypeScript・ESLint・Prettier・Jest・Swagger • 監視 Sentry • 設計 Clean Architecture
8. SDK Client • CIUのWebフロントエンド開発向けの SDK • 50個以上のパッケージから成るモノレポ 例： Cycloud UI UIライブラリ Cycloud Use クライアント ロジック Cycloud APIs APIクライアント Create Cycloud App ワンコマンドでWebUI 生成CLI 開発ツールの Config系 ESLint・Prettier・Jest etc…
9. SDK Client • CIUのWebフロントエンド開発向けの SDK • 50個以上のパッケージから成るモノレポ 例： Cycloud UI UIライブラリ Cycloud Use クライアント ロジック Cycloud APIs APIクライアント Create Cycloud App ワンコマンドでWebUI 生成CLI 開発ツールの Config系 ESLint・Prettier・Jest etc…
10. Cycloud APIsについて
11. Cycloud APIsとは •TypeScript製のAPIクライアントライブラリ サービスごとに分かれており、 適宜npmでインストールして使う •バックエンドの API定義を元に自動生成 API定義が変更されると自動生成が走る 生成されたTSをモノレポのパッケージ化
12. Cycloud APIsの構成 　
13. APIクライアントを 自動生成する
14. 【再掲】Cycloud APIsの構成 ここからは赤枠内の話をします　
15. API定義→API Clientの構成
16. API定義→API Clientの構成 青枠を掘り下げます
17. なぜSwaggerに変換？ • gPRCによるAPIをブラウザから呼び出すには Proxyが必要 CycloudのCLI向けのgRPC製APIをブラウザから使う • Proxyとしてgrpc-gatewayを利用している ProxyでgRPCをREST APIに変換 APIがgRPCであることを意識することなく使うための抽象化層
18. なぜSwagger 2.0に変換？ grpc-gatewayがSwagger 3.0以降をサポートしていない https://github.com/grpc-ecosystem/grpc-gateway/issues/441
19. 生成されたAPI Client
20. API Clientの使い方
21. APIレスポンスを元に表示するUI
22. 動いてそうなのでヨシ！
23. やがて浮き彫りになる問題...
24. 自動生成で発生した問題に 向き合う
25. ①Buf CLIプラグインのバグ field_behaviourというアノテーションが含まれた Protoをうまく変換できない https://github.com/grpc-ecosystem/grpc-gateway/issues/3058
26. Swaggerを3.0にすれば直るが grpc-gatewayは3.0に対応していない
27. 向き合う field_behaviorが無くても問題なかったので外す
28. ②Swagger 2.0にない仕様 pathプロパティに相当する Protoのフィールドを省略できない https://github.com/OAI/OpenAPI-Specification/issues/1045
29. Re: Swaggerを3.0にすれば直るが grpc-gatewayは3.0に対応していない
30. 向き合う openapi-generator-cliが中断しないようにバリデーションをスキップ・動作確認でカバー
31. まとめ
32. 技術で問題と向き合おう •バグや不具合に遭遇したら、まずは調査しよう 何が原因でどういった現象起きているか、客観的にまとめて解決方針を立てる →方針を元に動く。予測だけで動くと危険⚠ •ドキュメントや仕様書を読み込もう 今回であればProtoの仕様書やSwaggerの仕様書、GitHub Repoなど →AIツールを駆使しつつ、気になった箇所は自分の目で読み込むと⭕ •根本解決も視野に入れよう OSSであれば、直した内容を元にコントリビュートするとより良い →他のOSSユーザーも恩恵を享受できる🎉
33. 根本修正の例 開発中に遭遇した Storybook,Next.jsのバグを業務の一環で修正 https://github.com/storybookjs/storybook/pull/26787
34. 技術で幅広く貢献しよう💪
35. ありがとうございました