OpenAPI Generator を使ったときのエラーハンドリングについて

フロントエンドカンファレンス沖縄 2022 での登壇資料です。
https://frontend-conf.okinawa.jp/

OpenAPI Generator で API Client と型を自動生成して使った場合、エラーハンドリングはどうしたら良いのかについてお話しします。

## スライド内のリンク

「Reject Conference - Vue Fes Japan Online 2022
https://speakerdeck.com/ryamakuchi/vue-plus-typescript-de-0-1sabisukai-fa

RFC7807 のスキーマ例
https://tex2e.github.io/rfc-translater/html/rfc7807.html

ぼくのかんがえたさいきょうの API エラーレスポンスのフォーマット
https://zenn.dev/ryamakuchi/articles/d7c932afc57e30

サンプルコードはこちら
https://github.com/ryamakuchi/openapi-sample

Transcript

1. © 2012-2022 BASE, Inc. 1
   OpenAPI Generator を使ったときの
   エラーハンドリングについて
   フロントエンドカンファレンス沖縄2022（2022.11.19）
   千葉 リリィ（@chiba_rry）
   

   View Slide

2. © 2012-2022 BASE, Inc. 2
   自己紹介
   ● 最近バ美肉登壇しています！
   ○ アバターは「薄荷ちゃん」です 🌿
   ● 前回は「Reject Conference - Vue Fes Japan
   Online 2022」で登壇したりしました
   ○ https://speakerdeck.com/ryamakuchi/vue-plu
   s-typescript-de-0-1sabisukai-fa
   ● 直近 PJ ではフロントエンドだけでなく
   バックエンド（PHP）も書いてます 🐘
   ○ BASE はいろんなことに取り組めておもしろい
   千葉リリィ
   @chiba_rry
   @ryamakuchi
   

   View Slide

3. © 2012-2022 BASE, Inc. 3
   OpenAPI Generator で
   API Client と型を
   自動生成したやつを
   使いたい！
   🤔
   

   View Slide

4. © 2012-2022 BASE, Inc. 4
   けど、エラーハンドリング
   どうすれば良いかが
   分からない... 🙄
   

   View Slide

5. © 2012-2022 BASE, Inc. 5
   エラーレスポンスのスキーマ定義（RFC7807）
   エラーレスポンスのスキーマは
   RFC7807 を参考にしている。
   check 👉 ぼくのかんがえたさい
   きょうの API エラーレスポンス
   のフォーマット
   ※ あくまで参考にしているだけ
   で、準拠しているわけではない
   ことに注意
   RFC7807 は汎用的な弱い規約の
   ため、ここからスキーマを拡張
   していく必要がある。
   RFC7807 のスキーマ例
   https://tex2e.github.io/rfc-translater/html/rfc7807.html
   

   View Slide

6. © 2012-2022 BASE, Inc. 6
   RFC7807 参考にしたスキーマ定義
   これを基本の型とし、拡張して
   いく。
   この型で API が返すエラーレス
   ポンスはすべてまかなえる。
   RFC7807 との大きな差分
   ● type は URL 形式だがここで
   は string に省略
   ● instance を使うパターンは時
   間の関係で省略
   ● 拡張するときは payload プロ
   パティ（type: object）を
   使って拡張するようにした
   

   View Slide

7. © 2012-2022 BASE, Inc. 7
   エラーレスポンスの拡張（401 の場合）
   👈 allOf を使って型を拡張している
   👈 拡張するときは必ず payload プロパティ
   （type: object）を使って拡張する。
   今回はレスポンスにログイン用の URL を
   持たせた。
   同じ理屈で 422 バリデーションエラーの型を
   { payload: { errors: string[] } }
   のように定義することもできる。
   

   View Slide

8. © 2012-2022 BASE, Inc. 8
   エラーレスポンスの型（401 の場合）
   こんな感じで
   意図したとおりにスキーマが
   拡張された型が生成される
   👏
   

   View Slide

9. © 2012-2022 BASE, Inc. 9
   エラーレスポンスの定義
   👈 400 も 500 もレスポンスのスキーマは一緒
   👈 もし想定するレスポンスが複数あったら
   examples を個別に複数定義する
   👈 想定外の500エラーなど汎用的な
   エラーレスポンスの場合は個別に定義する
   必要がなくて楽ちん
   

   View Slide

10. © 2012-2022 BASE, Inc. 10
    ● 汎用的な API エラーレスポンス
    ○ 401: 認証失敗エラー
    ○ 400: パースエラー（わるい人の curl）
    ○ 404: リソースが見つからないエラー
    ○ 500: バックエンドのバグなど想定外の500エラー
    ● 個別に定義したい API エラーレスポンス
    ○ 422(400): バックエンドのバリデーションエラー
    ○ 500: 想定されている500エラー
    ● API エラーレスポンス以外のエラー
    ○ ネットワークなどの通信エラー
    ○ TypeError などフロントエンドのバグ
    API 通信のエラーハンドリング
    

    View Slide

11. © 2012-2022 BASE, Inc. 11
    ● 汎用的な API エラーレスポンス
    ○ 401: 認証失敗エラー
    ○ 400: パースエラー（わるい人の curl）
    ○ 404: リソースが見つからないエラー
    ○ 500: バックエンドのバグなど想定外の500エラー
    ● 個別に定義したい API エラーレスポンス
    ○ 422(400): バックエンドのバリデーションエラー
    ○ 500: 想定されている500エラー
    ● API エラーレスポンス以外のエラー
    ○ ネットワークなどの通信エラー
    ○ TypeError などフロントエンドのバグ
    1. まず API のエラーレスポンス
    とそれ以外のエラーについて
    分けたい
    API 通信のエラーハンドリング
    

    View Slide

12. © 2012-2022 BASE, Inc. 12
    ● 汎用的な API エラーレスポンス
    ○ 401: 認証失敗エラー
    ○ 400: パースエラー（わるい人の curl）
    ○ 404: リソースが見つからないエラー
    ○ 500: バックエンドのバグなど想定外の500エラー
    ● 個別に定義したい API エラーレスポンス
    ○ 422(400): バックエンドのバリデーションエラー
    ○ 500: 想定されている500エラー
    ● API エラーレスポンス以外のエラー
    ○ ネットワークなどの通信エラー
    ○ TypeError などフロントエンドのバグ
    1. まず API のエラーレスポンス
    とそれ以外のエラーについて
    分けたい
    2. 401 など API のエラーレスポ
    ンスで汎用的なエラーは都度
    ハンドリングしたくない
    API 通信のエラーハンドリング
    

    View Slide

13. © 2012-2022 BASE, Inc. 13
    ● 汎用的な API エラーレスポンス
    ○ 401: 認証失敗エラー
    ○ 400: パースエラー（わるい人の curl）
    ○ 404: リソースが見つからないエラー
    ○ 500: バックエンドのバグなど想定外の500エラー
    ● 個別に定義したい API エラーレスポンス
    ○ 422(400): バックエンドのバリデーションエラー
    ○ 500: 想定されている500エラー
    ● API エラーレスポンス以外のエラー
    ○ ネットワークなどの通信エラー
    ○ TypeError などフロントエンドのバグ
    1. まず API のエラーレスポンス
    とそれ以外のエラーについて
    分けたい
    2. 401 など API のエラーレスポ
    ンスで汎用的なエラーは都度
    ハンドリングしたくない
    3. エンドポイントで固有のエ
    ラーはレスポンスを受け取っ
    てハンドリングしたい
    API 通信のエラーハンドリング
    

    View Slide

14. © 2012-2022 BASE, Inc. 14
    1. まず API のエラーレスポンス
    とそれ以外のエラーについて
    分けたい
    API 通信のエラーハンドリング実装
    

    View Slide

15. © 2012-2022 BASE, Inc. 15
    1. まず API のエラーレスポンス
    とそれ以外のエラーについて
    分けたい
    2. 401 など API のエラーレスポ
    ンスで汎用的なエラーは都度
    ハンドリングしたくない
    API 通信のエラーハンドリング実装
    

    View Slide

16. © 2012-2022 BASE, Inc. 16
    1. まず API のエラーレスポンス
    とそれ以外のエラーについて
    分けたい
    2. 401 など API のエラーレスポ
    ンスで汎用的なエラーは都度
    ハンドリングしたくない
    3. エンドポイントで固有のエ
    ラーはレスポンスを受け取っ
    てハンドリングしたい
    API 通信のエラーハンドリング実装
    

    View Slide

17. © 2012-2022 BASE, Inc. 17
    1. 401 のエラーレスポンスが
    返ってきた場合は関数だけ渡
    して何もしない、みたいなこ
    とができる
    2. isAPIError 関数で個別に
    エラーハンドリングすること
    もできる
    API 通信のエラーハンドリング使い方
    

    View Slide

18. © 2012-2022 BASE, Inc. 18
    サンプルコードはこちら
    https://github.com/ryamakuchi/openapi-sample
    

    View Slide

19. © 2012-2022 BASE, Inc. 19
    まとめ
    

    View Slide

20. © 2012-2022 BASE, Inc. 20
    まとめ
    生成した API Client と型を使って楽できる
    一律同じようなエラーハンドリングができる
    スキーマ駆動開発をすることができる
    １
    ２
    ３
    

    View Slide

21. © 2012-2022 BASE, Inc. 21
    ご静聴
    ありがとうございました！
    

    View Slide