OpenAPIコード生成ライブラリを 『Orval』に移行した理由

2023年「春のJavaScript祭り」のLT登壇資料。

概要：OpenAPIからのコード自動生成ライブラリをopenapi-generatorからOrvalに移行した理由と効果について

Transcript

1. OpenAPIコード生成ライブラリを
   『Orval』に移行した理由
   早稲田大学4年　安井大晟（ytaisei）
   1
   

   View Slide

2. TABLE OF CONTENTS
   自己紹介
   01
   Orvalとは？
   03
   抱えていた課題
   02
   効果検証
   プロダクトが抱えていた
   課題を整理
   04
   Orvalの特徴を紹介
   他の自動生成ライブラリとの違
   いは
   導入後の効果
   2
   

   View Slide

3. 自己紹介
   01
   3
   

   View Slide

4. 自己紹介
   2019年：早稲田大学教育学部入学（元教員志望）
   2021年：42Tokyo入学
   2022年：エンジニアを目指し休学
   学生ピッチコンテスト等で受賞
   2023年：SaaS企業インターン
   4
   

   View Slide

5. 抱えていた課題
   プロダクトが抱えていた課題を整理
   02
   5
   

   View Slide

6. TypeScript
   （前提）使用している技術
   Axios
   HTTPクライアント コード生成ライブラリ
   openapi-generator
   テスト
   Testing Library
   言語 非同期状態管理
   React Query
   UIライブラリ
   React
   6
   

   View Slide

7. TypeScript
   （前提）使用している技術
   Axios
   HTTPクライアント コード生成ライブラリ
   Orval
   テスト
   Testing Library
   言語 非同期状態管理
   React Query
   UIライブラリ
   React
   7
   

   View Slide

8. React QueryのQuery Keyを
   安全に管理できていなかった
   抱えていた課題
   課題1 課題2
   Openapi-generator
   の使いづらさ
   ライブラリに対する不満 React Queryの設計上の問題
   8
   

   View Slide

9. Openapi-generatorの使いづらさ
   ● 出力ファイルの多さ
   ● 実行速度の遅さ
   ● 数多くのライブラリに対応している分、痒い所に手が届かない
   ○ 70近いclient generatorを用意
   ○ Mock生成、ファイルの出力方法 etc.
   9
   

   View Slide

10. React QueryのQuery Keyを
    安全に管理できていなかった
    これ
    キャッシュを管理する keyになるため、
    必ず一意性を保証する必要がある
    10
    

    View Slide

11. 公式でもQuery Keyを定数で管理することを
    推奨している
    11
    

    View Slide

12. 定数で管理するメリット
    Query Keyを文字列で指定しなくて良い
    ●
    ● Human Errorを防ぐ
    ● 保守性を高める
    12
    

    View Slide

13. React QueryのQuery Keyを
    安全に管理できていなかった
    抱えていた課題
    課題1 課題2
    Openapi-generator
    の使いづらさ
    ライブラリに対する不満 React Queryの設計上の問題
    13
    

    View Slide

14. Orvalとは？
    Orvalの特徴を紹介
    他の自動生成ライブラリとの違いは
    03
    14
    

    View Slide

15. Orvalとは？
    Orvalは、OpenAPIから型安全なコードを自動生成するツールであり、
    React Queryのカスタムフックも生成できます。APIドキュメントからクラ
    イアントコードを生成し、開発効率を向上させるだけでなく、型情報を提
    供してエラーを減らします。
    （ChatGPTに聞きました）
    15
    

    View Slide

16. まとめると
    ● TS製ライブラリ
    ● 高速なコード生成
    ● Mockの自動生成
    ● 柔軟な出力方法
    プロダクトとの相性が
    非常にいい
    REST設計で状態管理にReact QueryやSWRのような

    ライブラリを使用している場合、Orvalは高い価値を発揮する。
    16
    

    View Slide

17. Orvalが向かないケース
    ● スキーマが正しく定義されていない
    ○ 生成されるコードの質が落ちる
    ● テスト運用がされていない
    ○ Mockの自動生成が生きない
    ● React QueryやSWRを使っていない
    ○ カスタムフックの自動生成が生きない
    17
    

    View Slide

18. 生成されるコード
    1. HTTP通信ロジック
    2. Query Keyの生成関数
    3. 型定義
    4. React Queryのカスタムフック
    （特定の設定をした条件で）
    18
    1
    2
    3
    4
    

    View Slide

19. 2.　Query Keyの生成関数
    ● エンドポイントに沿ったQuery Keyを設定
    ● 一意であればなんでもいい
    ライブラリに任せたい！
    19
    

    View Slide

20. 4.　React Queryのカスタムフック
    1. エンドポイントごとにuseQueryの
    カスタムフックを実装する
    2. React Queryのオプションを失わない設計
    3. TDataをGenericsで渡せる
    4. QueryFn、QueryKeyを分けて実装する
    すべての条件を満たしている 👍
    20
    

    View Slide

21. 出力ファイル形式の柔軟性
    公式より 21
    

    View Slide

22. 効果検証
    導入後の効果
    04
    22
    

    View Slide

23. React QueryのQuery Keyを
    安全に管理できていなかった
    抱えていた課題
    課題1 課題2
    Openapi-generator
    の使いづらさ
    柔軟なカスタマイズと特定の技術下で
    高い価値を発揮！
    React Queryの設計を完全に任せられる！
    23
    

    View Slide

24. 24
    ● HTTP通信
    ○ openapi-generator
    ● React Queryの実装
    ● Query Keyの管理
    ● React Queryのオプション指定
    どれだけメンテナンスすべきコードが削減されたか
    

    View Slide

25. 25
    メンテナンスが必要なコードが大幅に削減
    ● HTTP通信
    ● React Queryの実装
    ● Query Keyの管理
    ● React Queryのオプション指定
    

    View Slide

26. ● React Queryのカスタムフック
    ● Query Keyの管理
    ● Mock関数の生成 etc.
    誰が担当しても同じ（似た）実装になるものは、
    ライブラリに任せることでHuman Errorを防ぎ、
    開発者体験を向上させる
    26
    

    View Slide

27. THANKS!
    ご清聴ありがとうございました
    ぜひ様々なイベントでのお声がけをお待
    ちしています！
    Twitter：https://twitter.com/ytaisei_
    GitHub：https://github.com/taisei-13046
    Qiita：https://qiita.com/taisei-13046
    Zenn：https://zenn.dev/taisei_13046
    27
    

    View Slide