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）
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
3. © 2012-2022 BASE, Inc. 3 OpenAPI Generator で API Client と型を 自動生成したやつを 使いたい！ 🤔
4. © 2012-2022 BASE, Inc. 4 けど、エラーハンドリング どうすれば良いかが 分からない... 🙄
5. © 2012-2022 BASE, Inc. 5 エラーレスポンスのスキーマ定義（RFC7807） エラーレスポンスのスキーマは RFC7807 を参考にしている。 check 👉 ぼくのかんがえたさい きょうの API エラーレスポンス のフォーマット ※ あくまで参考にしているだけ で、準拠しているわけではない ことに注意 RFC7807 は汎用的な弱い規約の ため、ここからスキーマを拡張 していく必要がある。 RFC7807 のスキーマ例 https://tex2e.github.io/rfc-translater/html/rfc7807.html
6. © 2012-2022 BASE, Inc. 6 RFC7807 参考にしたスキーマ定義 これを基本の型とし、拡張して いく。 この型で API が返すエラーレス ポンスはすべてまかなえる。 RFC7807 との大きな差分 • type は URL 形式だがここで は string に省略 • instance を使うパターンは時 間の関係で省略 • 拡張するときは payload プロ パティ（type: object）を 使って拡張するようにした
7. © 2012-2022 BASE, Inc. 7 エラーレスポンスの拡張（401 の場合） 👈 allOf を使って型を拡張している 👈 拡張するときは必ず payload プロパティ （type: object）を使って拡張する。 今回はレスポンスにログイン用の URL を 持たせた。 同じ理屈で 422 バリデーションエラーの型を { payload: { errors: string[] } } のように定義することもできる。
8. © 2012-2022 BASE, Inc. 8 エラーレスポンスの型（401 の場合） こんな感じで 意図したとおりにスキーマが 拡張された型が生成される 👏
9. © 2012-2022 BASE, Inc. 9 エラーレスポンスの定義 👈 400 も 500 もレスポンスのスキーマは一緒 👈 もし想定するレスポンスが複数あったら examples を個別に複数定義する 👈 想定外の500エラーなど汎用的な エラーレスポンスの場合は個別に定義する 必要がなくて楽ちん
10. © 2012-2022 BASE, Inc. 10 • 汎用的な API エラーレスポンス ◦ 401: 認証失敗エラー ◦ 400: パースエラー（わるい人の curl） ◦ 404: リソースが見つからないエラー ◦ 500: バックエンドのバグなど想定外の500エラー • 個別に定義したい API エラーレスポンス ◦ 422(400): バックエンドのバリデーションエラー ◦ 500: 想定されている500エラー • API エラーレスポンス以外のエラー ◦ ネットワークなどの通信エラー ◦ TypeError などフロントエンドのバグ API 通信のエラーハンドリング
11. © 2012-2022 BASE, Inc. 11 • 汎用的な API エラーレスポンス ◦ 401: 認証失敗エラー ◦ 400: パースエラー（わるい人の curl） ◦ 404: リソースが見つからないエラー ◦ 500: バックエンドのバグなど想定外の500エラー • 個別に定義したい API エラーレスポンス ◦ 422(400): バックエンドのバリデーションエラー ◦ 500: 想定されている500エラー • API エラーレスポンス以外のエラー ◦ ネットワークなどの通信エラー ◦ TypeError などフロントエンドのバグ 1. まず API のエラーレスポンス とそれ以外のエラーについて 分けたい API 通信のエラーハンドリング
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 通信のエラーハンドリング
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 通信のエラーハンドリング
14. © 2012-2022 BASE, Inc. 14 1. まず API のエラーレスポンス とそれ以外のエラーについて 分けたい API 通信のエラーハンドリング実装
15. © 2012-2022 BASE, Inc. 15 1. まず API のエラーレスポンス とそれ以外のエラーについて 分けたい 2. 401 など API のエラーレスポ ンスで汎用的なエラーは都度 ハンドリングしたくない API 通信のエラーハンドリング実装
16. © 2012-2022 BASE, Inc. 16 1. まず API のエラーレスポンス とそれ以外のエラーについて 分けたい 2. 401 など API のエラーレスポ ンスで汎用的なエラーは都度 ハンドリングしたくない 3. エンドポイントで固有のエ ラーはレスポンスを受け取っ てハンドリングしたい API 通信のエラーハンドリング実装
17. © 2012-2022 BASE, Inc. 17 1. 401 のエラーレスポンスが 返ってきた場合は関数だけ渡 して何もしない、みたいなこ とができる 2. isAPIError 関数で個別に エラーハンドリングすること もできる API 通信のエラーハンドリング使い方
18. © 2012-2022 BASE, Inc. 18 サンプルコードはこちら https://github.com/ryamakuchi/openapi-sample
19. © 2012-2022 BASE, Inc. 19 まとめ
20. © 2012-2022 BASE, Inc. 20 まとめ 生成した API Client と型を使って楽できる 一律同じようなエラーハンドリングができる スキーマ駆動開発をすることができる １ ２ ３
21. © 2012-2022 BASE, Inc. 21 ご静聴 ありがとうございました！