OpenAPI Generator と TypeScript による型安全なスキーマ駆動開発

【READYFOR】実践！フロントエンド分離戦略
https://readyfor.connpass.com/event/198730/

Transcript

1. 1 OpenAPI Generator と TypeScript による型安全なスキーマ駆動開発 2021.2.5 菅原 弘太郎
2. 2 自己紹介 #readyfor_meetup Kotaro Sugawara @kotarella1110 • フロントエンドエンジニア • 2020年11月入社 • 岩手県在住 • React と TypeScript が好き • React Hook Form のメンバー ◦ TypeScript の型改善を中心にコントリビュート
3. 3 フロントエンドとバックエンドの分離 #readyfor_meetup
4. 4 フロントエンドとバックエンドの分離 READYFOR の取り組み #readyfor_meetup • READYFOR は モノリシックな Ruby on Rails のサービス • 様々なドメインが入り組んだ一つのモノリシックなサービスからドメイン毎に 分離されたサービス（マイクロサービス化）を目指している • 現状、フロントエンドとバックエンドの分離フェーズ ◦ フロントエンド: SPA（TypeScript/Next.js） ◦ バックエンド: REST API（Ruby）
5. 5 フロントエンドとバックエンドの分離 READYFOR の取り組み #readyfor_meetup • READYFOR は モノリシックな Ruby on Rails のサービス • 様々なドメインが入り組んだ一つのモノリシックなサービスからドメイン毎に 分離されたサービス（マイクロサービス化）を目指している • 現状、フロントエンドとバックエンドの分離フェーズ ◦ フロントエンド: SPA（TypeScript/Next.js） ◦ バックエンド: REST API ちょうどこのタイミングで入社 🎉
6. 6 フロントエンドとバックエンドの分離 入社したものの… #readyfor_meetup スキーマ駆動開発ってなんだ？ 🤔
7. 7 フロントエンドとバックエンドの分離 本日お話しすること #readyfor_meetup • スキーマ駆動開発とは何か？どんなメリットがあるか？ • どんなツールを活用しているか？ • 3ヶ月スキーマ駆動開発を実践してみての所感
8. 8 フロントエンドとバックエンドの分離 #readyfor_meetup これからスキーマ駆動開発を実践したい方のご参考になれば幸いです 🙏
9. 9 スキーマ駆動開発 #readyfor_meetup
10. 10 スキーマ駆動開発 SPA と API 開発における悩み #readyfor_meetup • API 仕様書のフォーマットが人によってバラバラ • API 仕様書と実装が乖離 ◦ API 仕様書がメンテナンスされていない ◦ API 仕様書の変更に気付かない • API の実装を待たないとフロントの開発に着手できない • API のリクエストやレスポンスが想定していたものと違う ◦ 修正コストが発生
11. 11 スキーマ駆動開発の出番です 💪 #readyfor_meetup
12. 12 スキーマ駆動開発 スキーマとは？ #readyfor_meetup • 定められた形式で記述したもの • Web API の仕様定義 ◦ エンドポイント ◦ リクエストやレスポンスのデータ構造 ◦ 値の型やフォーマット
13. 13 スキーマ駆動開発 スキーマ駆動開発とは？ #readyfor_meetup Web API の開発者と利用者でスキーマ設計を行い スキーマを中心とした開発を行うこと
14. 14 スキーマ駆動開発 開発の中心にスキーマがある 様々なツールを活用してこれを実現する #readyfor_meetup 仕様の相談 クライアントの 実装 モックサーバー の活用 ドキュメントの 生成 コードの生成 API の実装 スキーマ
15. 15 スキーマ駆動開発 開発フローの違い #readyfor_meetup スキーマ駆動開発以前 設計 実装 実装 完成 完成 Web API 開発者 Web API 利用者 検証 実装を待つ 必要がある スキーマ駆動開発以降 完成 完成 Web API 開発者 Web API 利用者 スキーマ設計 検証 実装 実装 実装を待つ 必要がない
16. 16 スキーマの定義 仕様の相談 クライアントの 実装 モックサーバー の活用 ドキュメントの 生成 コードの生成 API の実装 スキーマ #readyfor_meetup
17. 17 スキーマ定義 OpenAPI #readyfor_meetup • 旧 Swagger Specification • Web APIを記述するためのフォーマット • Open API Initiative により推進 • スキーマを JSON/YAML 形式で記述することができる • READYFOR では OpenAPI 3.0 を使用
18. 18 スキーマ定義 OpenAPI #readyfor_meetup • /pets/{petId} へ GET リクエスト ◦ petId: 必須・string 型 • JSON 形式で 200 レスポンス ◦ id: 必須・integer 型で・int64 フォーマット ◦ name: 必須・string 型 ◦ tag: string 型
19. 19 スキーマ定義 スキーマ定義の仕方 #readyfor_meetup • Swagger Editor ◦ スキーマを編集しながらプレビューが可能なエディタ • Stoplight Studio ◦ スキーマを定義するための GUI エディタ ◦ Stoplight 社が提供 ◦ Swagger Editor と違い GUI のため OpenAPI のスキーマ定義の仕方知らなく ても編集することができる（OpenAPI 初心者に優しい） ◦ Git との連携やモックサーバーの統合など豊富な機能を備えている
20. 20 スキーマ定義 Swagger Editor #readyfor_meetup
21. 21 スキーマ定義 Stoplight Studio #readyfor_meetup
22. 22 ドキュメントの自動生成 仕様の相談 クライアントの 実装 モックサーバー の活用 ドキュメントの 生成 コードの生成 API の実装 スキーマ #readyfor_meetup
23. 23 ドキュメントの自動生成 Swagger UI #readyfor_meetup • OpenAPI のスキーマから見やすいドキュメントを生成することができる • Swagger Editior のプレビュー • スキーマからドキュメントが生成されるので信頼できる
24. 24 ドキュメントの自動生成 Swagger UI #readyfor_meetup
25. 25 コードの自動生成 仕様の相談 クライアントの 実装 モックサーバー の活用 ドキュメントの 生成 コードの生成 API の実装 スキーマ #readyfor_meetup
26. 26 コードの自動生成 OpenAPI Generator #readyfor_meetup • OpenAPI のスキーマから API クライアントなどのコードを生成することがで きる • Swagger Codegen からフォークされコミュニティ主導で開発されている • 多くの言語・フレームワークをサポート
27. 27 • openapi.yml ファイルを元に src/types/api ディレク トリに生成ファイルを出力 • READYFOR では ジェネレーターとして typescript-fetch を使用 ◦ typescript-fetch 以外にも typescript-axios や typescript-angular、typescript-redux-query な ど様々存在する コードの自動生成 OpenAPI Generator #readyfor_meetup
28. 28 コードの自動生成 API クライアントやモデル、リクエスト・レスポンスの型が生成される #readyfor_meetup
29. 29 コードの自動生成 型安全 #readyfor_meetup • スキーマから自動で型が生成される ◦ リクエストやレスポンスの型を信頼できる ◦ 定型コードを記述するコストも減る • スキーマが変更された際もビルドエラーで修正箇所を把握できる
30. 30 コードの自動生成 ハマりどころ1 #readyfor_meetup tags を指定せずにスキーマを定義すると、API クラス名が自動で生成されてしまう
31. 31 tags を指定してスキーマを定義すると、意図した API クラス名で生成できる コードの自動生成 ハマりどころ1 #readyfor_meetup
32. 32 コードの自動生成 ハマりどころ2 #readyfor_meetup operationId を指定せずにスキーマを定義すると、 API クラスのメソッド名やリクエストデータの型名が自動で生成されてしまう
33. 33 コードの自動生成 ハマりどころ2 #readyfor_meetup operationId を指定してスキーマを定義すると、意図した命名で生成できる
34. 34 コードの自動生成 ハマりどころ3 #readyfor_meetup components/schema を使用せずにスキーマを定義すると、 InlineResponsXXX のようなレスポンスデータの型名が自動で生成されてしまう
35. 35 コードの自動生成 ハマりどころ3 #readyfor_meetup components/schema を使用してスキーマを定義すると意図した型名で生成できる
36. 36 モックサーバーの活用 仕様の相談 クライアントの 実装 モックサーバー の活用 ドキュメントの 生成 コードの生成 API の実装 スキーマ #readyfor_meetup
37. 37 モックサーバーの活用 Stoplight Prism #readyfor_meetup • OpenAPI のスキーマ定義から API のモックサーバーを起動できる ◦ スキーマに基づいたエンドポイント・レスポンス ◦ API の実装を待たずに開発に着手することができる • Stoplight 社が提供 • Stoplight Studio にもモックサーバーとして統合されている
38. 38 • openapi.yaml ファイルからモックサーバーを起動 • デフォルトではスタティックレスポンスを生成 ◦ 毎回同じデータをレスポンス ◦ スキーマに Example が定義されていればそれをレ スポンスする ◦ スタティックレスポンスの生成条件がやや複雑 ▪ 詳しくはこちらを参照 • --dynamic/-d フラグを使用することでダイナミックレスポン スを生成 ◦ 毎回異なるデータをレスポンス モックサーバーの活用 Stoplight Prism #readyfor_meetup
39. 39 • code ◦ 指定したステータスコードに応じてレスポンス • example ◦ スキーマに定義された Example のキー名を指定す ることで、その Example をレスポンス • dynamic ◦ true を指定することでダイナミックレスポンスを有効 化 モックサーバーの活用 Prefer ヘッダーを渡すことでレスポンスの変更が可能 #readyfor_meetup
40. 40 例えば「入力フォームの Submit ボタンを押して 422 エラーが レスポンスされたとき、エラーメッセージが表示されるか」など のテストが簡単にできる • cy.server でバックエンドの呼び出しを待つ • onAnyRequest を使用してリクストヘッダーをカスタマイズ ◦ Prefer ヘッダーを追加 モックサーバーの活用 Cypress と相性が良い #readyfor_meetup
41. 41 所感 #readyfor_meetup
42. 42 所感 スキーマ駆動開発を実践してみてよかったこと #readyfor_meetup • API ドキュメントが信頼できる • TypeScript のコードが生成されるため型安全 • モックサーバーによる効率的・テスタブルな開発 • バックエンドエンジニアとも認識を合わせやすい ◦ OpenAPI のリポジトリ上の PR 上でやりとり ◦ 考慮漏れの発覚や要望などが発生した場合 PR を送る ◦ マージされればすぐに開発に着手できる
43. 43 所感 スキーマ駆動開発を実践してみて辛いと感じたこと #readyfor_meetup • OpenAPI Generator によって生成されたコードで型エラー ◦ oneOf/allOf を使用したスキーマ定義でよく発生する ◦ openapi-generator-cli の -g オプションで指定するジェネレーターを typescript-fetch から typescript-axios に変更すると正しいコードが生成できたりする…（逆もありそう）
44. 44 所感 スキーマ駆動開発を実践してみて辛いと感じたこと #readyfor_meetup • 生成される型が最善ではない ◦ enum は Enum 型で出力される（Union 型に出力するオプションがほしい） ◦ nullable な enum は nullable にならない ◦ date/date-time フォーマットは Date 型で出力される（string 型にしてほしい） ▪ typescript-fetch のみ？ • openapi-generator-cli の --type-mappings オプションで型をマッピングすることができ る（--type-mappings=date=string,DateTime=string） • 型をマッピングしても API クラス側で型エラーが発生する ▪ typescript-axios/typescript-angular などは string 型で出力される
45. 45 所感 スキーマ駆動開発を実践する前に検討した方が良さそうなこと #readyfor_meetup • OpenAPI Generator によって生成された API クライアントを使用するか？それとも型定義のみを使 用するか？ ◦ 生成された API クライアントを使用する場合、当然それに依存することになる ◦ 生成された API クライアントのコードをあらかじめ読んで、使用するか判断した方が良い • openapi-generator-cli の -g オプションで指定するジェネレーターをどれにするか？ ◦ 型定義のみを使用する場合は、先に説明した出力される型定義との兼ね合いをみて決定した方 が良さそう
46. 46 所感 スキーマ駆動開発を実践してみて重要だと感じたこと #readyfor_meetup • フロントエンドとバックエンド共にスキーマからコード生成すること • フロント側のみスキーマからコードを生成しても、スキーマと API の実装に乖離が発生する可能性が 高い • 最悪の場合、スキーマがメンテナンスされなくなる
47. 47 スキーマ駆動開発はメリットがデメリットをはるかに上回ります 興味を持った方は是非実践してみてください 🙌 #readyfor_meetup
48. 48 ご清聴いただきありがとうございました 🙇 #readyfor_meetup