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

by Kotaro Sugawara

Slide 1

Slide 1 text

1 OpenAPI Generator と TypeScript による型安全なスキーマ駆動開発 2021.2.5 菅原弘太郎

Slide 2

Slide 2 text

2 自己紹介 #readyfor_meetup Kotaro Sugawara @kotarella1110 ● フロントエンドエンジニア ● 2020年11月入社 ● 岩手県在住 ● React と TypeScript が好き ● React Hook Form のメンバー ○ TypeScript の型改善を中心にコントリビュート

Slide 3

Slide 3 text

3 フロントエンドとバックエンドの分離 #readyfor_meetup

Slide 4

Slide 4 text

4 フロントエンドとバックエンドの分離 READYFOR の取り組み #readyfor_meetup ● READYFOR はモノリシックな Ruby on Rails のサービス ● 様々なドメインが入り組んだ一つのモノリシックなサービスからドメイン毎に分離されたサービス（マイクロサービス化）を目指している ● 現状、フロントエンドとバックエンドの分離フェーズ ○ フロントエンド: SPA（TypeScript/Next.js） ○ バックエンド: REST API（Ruby）

Slide 5

Slide 5 text

5 フロントエンドとバックエンドの分離 READYFOR の取り組み #readyfor_meetup ● READYFOR はモノリシックな Ruby on Rails のサービス ● 様々なドメインが入り組んだ一つのモノリシックなサービスからドメイン毎に分離されたサービス（マイクロサービス化）を目指している ● 現状、フロントエンドとバックエンドの分離フェーズ ○ フロントエンド: SPA（TypeScript/Next.js） ○ バックエンド: REST API ちょうどこのタイミングで入社 🎉

Slide 6

Slide 6 text

6 フロントエンドとバックエンドの分離入社したものの… #readyfor_meetup スキーマ駆動開発ってなんだ？ 🤔

Slide 7

Slide 7 text

7 フロントエンドとバックエンドの分離本日お話しすること #readyfor_meetup ● スキーマ駆動開発とは何か？どんなメリットがあるか？ ● どんなツールを活用しているか？ ● 3ヶ月スキーマ駆動開発を実践してみての所感

Slide 8

Slide 8 text

8 フロントエンドとバックエンドの分離 #readyfor_meetup これからスキーマ駆動開発を実践したい方のご参考になれば幸いです 🙏

Slide 9

Slide 9 text

9 スキーマ駆動開発 #readyfor_meetup

Slide 10

Slide 10 text

10 スキーマ駆動開発 SPA と API 開発における悩み #readyfor_meetup ● API 仕様書のフォーマットが人によってバラバラ ● API 仕様書と実装が乖離 ○ API 仕様書がメンテナンスされていない ○ API 仕様書の変更に気付かない ● API の実装を待たないとフロントの開発に着手できない ● API のリクエストやレスポンスが想定していたものと違う ○ 修正コストが発生

Slide 11

Slide 11 text

11 スキーマ駆動開発の出番です 💪 #readyfor_meetup

Slide 12

Slide 12 text

12 スキーマ駆動開発スキーマとは？ #readyfor_meetup ● 定められた形式で記述したもの ● Web API の仕様定義 ○ エンドポイント ○ リクエストやレスポンスのデータ構造 ○ 値の型やフォーマット

Slide 13

Slide 13 text

13 スキーマ駆動開発スキーマ駆動開発とは？ #readyfor_meetup Web API の開発者と利用者でスキーマ設計を行いスキーマを中心とした開発を行うこと

Slide 14

Slide 14 text

14 スキーマ駆動開発開発の中心にスキーマがある様々なツールを活用してこれを実現する #readyfor_meetup 仕様の相談クライアントの実装モックサーバーの活用ドキュメントの生成コードの生成 API の実装スキーマ

Slide 15

Slide 15 text

15 スキーマ駆動開発開発フローの違い #readyfor_meetup スキーマ駆動開発以前設計実装実装完成完成 Web API 開発者 Web API 利用者検証実装を待つ必要があるスキーマ駆動開発以降完成完成 Web API 開発者 Web API 利用者スキーマ設計検証実装実装実装を待つ必要がない

Slide 16

Slide 16 text

16 スキーマの定義仕様の相談クライアントの実装モックサーバーの活用ドキュメントの生成コードの生成 API の実装スキーマ #readyfor_meetup

Slide 17

Slide 17 text

17 スキーマ定義 OpenAPI #readyfor_meetup ● 旧 Swagger Speciﬁcation ● Web APIを記述するためのフォーマット ● Open API Initiative により推進 ● スキーマを JSON/YAML 形式で記述することができる ● READYFOR では OpenAPI 3.0 を使用

Slide 18

Slide 18 text

18 スキーマ定義 OpenAPI #readyfor_meetup ● /pets/{petId} へ GET リクエスト ○ petId: 必須・string 型 ● JSON 形式で 200 レスポンス ○ id: 必須・integer 型で・int64 フォーマット ○ name: 必須・string 型 ○ tag: string 型

Slide 19

Slide 19 text

19 スキーマ定義スキーマ定義の仕方 #readyfor_meetup ● Swagger Editor ○ スキーマを編集しながらプレビューが可能なエディタ ● Stoplight Studio ○ スキーマを定義するための GUI エディタ ○ Stoplight 社が提供 ○ Swagger Editor と違い GUI のため OpenAPI のスキーマ定義の仕方知らなくても編集することができる（OpenAPI 初心者に優しい） ○ Git との連携やモックサーバーの統合など豊富な機能を備えている

Slide 20

Slide 20 text

20 スキーマ定義 Swagger Editor #readyfor_meetup

Slide 21

Slide 21 text

21 スキーマ定義 Stoplight Studio #readyfor_meetup

Slide 22

Slide 22 text

22 ドキュメントの自動生成仕様の相談クライアントの実装モックサーバーの活用ドキュメントの生成コードの生成 API の実装スキーマ #readyfor_meetup

Slide 23

Slide 23 text

23 ドキュメントの自動生成 Swagger UI #readyfor_meetup ● OpenAPI のスキーマから見やすいドキュメントを生成することができる ● Swagger Editior のプレビュー ● スキーマからドキュメントが生成されるので信頼できる

Slide 24

Slide 24 text

24 ドキュメントの自動生成 Swagger UI #readyfor_meetup

Slide 25

Slide 25 text

25 コードの自動生成仕様の相談クライアントの実装モックサーバーの活用ドキュメントの生成コードの生成 API の実装スキーマ #readyfor_meetup

Slide 26

Slide 26 text

26 コードの自動生成 OpenAPI Generator #readyfor_meetup ● OpenAPI のスキーマから API クライアントなどのコードを生成することができる ● Swagger Codegen からフォークされコミュニティ主導で開発されている ● 多くの言語・フレームワークをサポート

Slide 27

Slide 27 text

27 ● openapi.yml ファイルを元に src/types/api ディレクトリに生成ファイルを出力 ● READYFOR ではジェネレーターとして typescript-fetch を使用 ○ typescript-fetch 以外にも typescript-axios や typescript-angular、typescript-redux-query など様々存在するコードの自動生成 OpenAPI Generator #readyfor_meetup

Slide 28

Slide 28 text

28 コードの自動生成 API クライアントやモデル、リクエスト・レスポンスの型が生成される #readyfor_meetup

Slide 29

Slide 29 text

29 コードの自動生成型安全 #readyfor_meetup ● スキーマから自動で型が生成される ○ リクエストやレスポンスの型を信頼できる ○ 定型コードを記述するコストも減る ● スキーマが変更された際もビルドエラーで修正箇所を把握できる

Slide 30

Slide 30 text

30 コードの自動生成ハマりどころ1 #readyfor_meetup tags を指定せずにスキーマを定義すると、API クラス名が自動で生成されてしまう

Slide 31

Slide 31 text

31 tags を指定してスキーマを定義すると、意図した API クラス名で生成できるコードの自動生成ハマりどころ1 #readyfor_meetup

Slide 32

Slide 32 text

32 コードの自動生成ハマりどころ2 #readyfor_meetup operationId を指定せずにスキーマを定義すると、 API クラスのメソッド名やリクエストデータの型名が自動で生成されてしまう

Slide 33

Slide 33 text

33 コードの自動生成ハマりどころ2 #readyfor_meetup operationId を指定してスキーマを定義すると、意図した命名で生成できる

Slide 34

Slide 34 text

34 コードの自動生成ハマりどころ3 #readyfor_meetup components/schema を使用せずにスキーマを定義すると、 InlineResponsXXX のようなレスポンスデータの型名が自動で生成されてしまう

Slide 35

Slide 35 text

35 コードの自動生成ハマりどころ3 #readyfor_meetup components/schema を使用してスキーマを定義すると意図した型名で生成できる

Slide 36

Slide 36 text

36 モックサーバーの活用仕様の相談クライアントの実装モックサーバーの活用ドキュメントの生成コードの生成 API の実装スキーマ #readyfor_meetup

Slide 37

Slide 37 text

37 モックサーバーの活用 Stoplight Prism #readyfor_meetup ● OpenAPI のスキーマ定義から API のモックサーバーを起動できる ○ スキーマに基づいたエンドポイント・レスポンス ○ API の実装を待たずに開発に着手することができる ● Stoplight 社が提供 ● Stoplight Studio にもモックサーバーとして統合されている

Slide 38

Slide 38 text

38 ● openapi.yaml ファイルからモックサーバーを起動 ● デフォルトではスタティックレスポンスを生成 ○ 毎回同じデータをレスポンス ○ スキーマに Example が定義されていればそれをレスポンスする ○ スタティックレスポンスの生成条件がやや複雑 ■ 詳しくはこちらを参照 ● --dynamic/-d フラグを使用することでダイナミックレスポンスを生成 ○ 毎回異なるデータをレスポンスモックサーバーの活用 Stoplight Prism #readyfor_meetup

Slide 39

Slide 39 text

39 ● code ○ 指定したステータスコードに応じてレスポンス ● example ○ スキーマに定義された Example のキー名を指定することで、その Example をレスポンス ● dynamic ○ true を指定することでダイナミックレスポンスを有効化モックサーバーの活用 Prefer ヘッダーを渡すことでレスポンスの変更が可能 #readyfor_meetup

Slide 40

Slide 40 text

40 例えば「入力フォームの Submit ボタンを押して 422 エラーがレスポンスされたとき、エラーメッセージが表示されるか」などのテストが簡単にできる ● cy.server でバックエンドの呼び出しを待つ ● onAnyRequest を使用してリクストヘッダーをカスタマイズ ○ Prefer ヘッダーを追加モックサーバーの活用 Cypress と相性が良い #readyfor_meetup

Slide 41

Slide 41 text

41 所感 #readyfor_meetup

Slide 42

Slide 42 text

42 所感スキーマ駆動開発を実践してみてよかったこと #readyfor_meetup ● API ドキュメントが信頼できる ● TypeScript のコードが生成されるため型安全 ● モックサーバーによる効率的・テスタブルな開発 ● バックエンドエンジニアとも認識を合わせやすい ○ OpenAPI のリポジトリ上の PR 上でやりとり ○ 考慮漏れの発覚や要望などが発生した場合 PR を送る ○ マージされればすぐに開発に着手できる

Slide 43

Slide 43 text

43 所感スキーマ駆動開発を実践してみて辛いと感じたこと #readyfor_meetup ● OpenAPI Generator によって生成されたコードで型エラー ○ oneOf/allOf を使用したスキーマ定義でよく発生する ○ openapi-generator-cli の -g オプションで指定するジェネレーターを typescript-fetch から typescript-axios に変更すると正しいコードが生成できたりする…（逆もありそう）

Slide 44

Slide 44 text

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 型で出力される

Slide 45

Slide 45 text

45 所感スキーマ駆動開発を実践する前に検討した方が良さそうなこと #readyfor_meetup ● OpenAPI Generator によって生成された API クライアントを使用するか？それとも型定義のみを使用するか？ ○ 生成された API クライアントを使用する場合、当然それに依存することになる ○ 生成された API クライアントのコードをあらかじめ読んで、使用するか判断した方が良い ● openapi-generator-cli の -g オプションで指定するジェネレーターをどれにするか？ ○ 型定義のみを使用する場合は、先に説明した出力される型定義との兼ね合いをみて決定した方が良さそう

Slide 46

Slide 46 text

46 所感スキーマ駆動開発を実践してみて重要だと感じたこと #readyfor_meetup ● フロントエンドとバックエンド共にスキーマからコード生成すること ● フロント側のみスキーマからコードを生成しても、スキーマと API の実装に乖離が発生する可能性が高い ● 最悪の場合、スキーマがメンテナンスされなくなる

Slide 47

Slide 47 text

47 スキーマ駆動開発はメリットがデメリットをはるかに上回ります興味を持った方は是非実践してみてください 🙌 #readyfor_meetup

Slide 48

Slide 48 text

48 ご清聴いただきありがとうございました 🙇 #readyfor_meetup