Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
OpenAPI Generator と TypeScript による型安全なスキーマ駆動開発
Search
Kotaro Sugawara
February 05, 2021
Technology
4
46k
OpenAPI Generator と TypeScript による型安全なスキーマ駆動開発
【READYFOR】実践!フロントエンド分離戦略
https://readyfor.connpass.com/event/198730/
Kotaro Sugawara
February 05, 2021
Tweet
Share
More Decks by Kotaro Sugawara
See All by Kotaro Sugawara
React Hook Form はどのように再レンダリングを最適化しているのか?
kotarella1110
9
6k
Other Decks in Technology
See All in Technology
プログラミング写経のすすめ
natsutan
0
170
JAWS-UG 事務局 の「これまで」から みんなで「ここから」を考えよう
miu_crescent
2
140
エンジニア向け会社紹介資料
caddi_eng
14
270k
全社を巻き込んだ業務オペレーション改善と、それは事業成長に貢献しているのか?を実感した話
marroooon
0
150
テクニカルライターのチームで「目標」をどう決めたか / MVV for a Team of Technical Writers
lycorptech_jp
PRO
3
160
人工衛星開発のための C2A フレームワークとその開発体験
sksat
0
110
Snowflakeでスロークエリ改善に取り組んだ話
tabata0208
0
130
ラブグラフ紹介資料 〜プロダクト解体新書〜 / Lovegraph Product Deck
lovegraph
0
14k
多数のWebサービスをECS/Fargate構成で効率よく構築・運用するなら copilot-cli
interu
2
170
MobileActOsaka_241018.pdf
akaitadaaki
0
110
RAG: from dumb implementation to serious results
glaforge
0
670
Azure AI servicesと歯のおはなし/AzureTravelers_Fukuoka2024_baba
nina01
1
110
Featured
See All Featured
StorybookのUI Testing Handbookを読んだ
zakiyama
26
5.2k
How STYLIGHT went responsive
nonsquared
95
5.1k
We Have a Design System, Now What?
morganepeng
50
7.2k
Stop Working from a Prison Cell
hatefulcrawdad
267
20k
I Don’t Have Time: Getting Over the Fear to Launch Your Podcast
jcasabona
27
1.9k
Optimising Largest Contentful Paint
csswizardry
31
2.9k
Art, The Web, and Tiny UX
lynnandtonic
296
20k
Understanding Cognitive Biases in Performance Measurement
bluesmoon
26
1.4k
For a Future-Friendly Web
brad_frost
174
9.4k
Pencils Down: Stop Designing & Start Developing
hursman
119
11k
Principles of Awesome APIs and How to Build Them.
keavy
126
17k
Embracing the Ebb and Flow
colly
84
4.4k
Transcript
1 OpenAPI Generator と TypeScript による型安全なスキーマ駆動開発 2021.2.5 菅原 弘太郎
2 自己紹介 #readyfor_meetup Kotaro Sugawara @kotarella1110 • フロントエンドエンジニア • 2020年11月入社
• 岩手県在住 • React と TypeScript が好き • React Hook Form のメンバー ◦ TypeScript の型改善を中心にコントリビュート
3 フロントエンドとバックエンドの分離 #readyfor_meetup
4 フロントエンドとバックエンドの分離 READYFOR の取り組み #readyfor_meetup • READYFOR は モノリシックな Ruby
on Rails のサービス • 様々なドメインが入り組んだ一つのモノリシックなサービスからドメイン毎に 分離されたサービス(マイクロサービス化)を目指している • 現状、フロントエンドとバックエンドの分離フェーズ ◦ フロントエンド: SPA(TypeScript/Next.js) ◦ バックエンド: REST API(Ruby)
5 フロントエンドとバックエンドの分離 READYFOR の取り組み #readyfor_meetup • READYFOR は モノリシックな Ruby
on Rails のサービス • 様々なドメインが入り組んだ一つのモノリシックなサービスからドメイン毎に 分離されたサービス(マイクロサービス化)を目指している • 現状、フロントエンドとバックエンドの分離フェーズ ◦ フロントエンド: SPA(TypeScript/Next.js) ◦ バックエンド: REST API ちょうどこのタイミングで入社 🎉
6 フロントエンドとバックエンドの分離 入社したものの… #readyfor_meetup スキーマ駆動開発ってなんだ? 🤔
7 フロントエンドとバックエンドの分離 本日お話しすること #readyfor_meetup • スキーマ駆動開発とは何か?どんなメリットがあるか? • どんなツールを活用しているか? • 3ヶ月スキーマ駆動開発を実践してみての所感
8 フロントエンドとバックエンドの分離 #readyfor_meetup これからスキーマ駆動開発を実践したい方のご参考になれば幸いです 🙏
9 スキーマ駆動開発 #readyfor_meetup
10 スキーマ駆動開発 SPA と API 開発における悩み #readyfor_meetup • API 仕様書のフォーマットが人によってバラバラ
• API 仕様書と実装が乖離 ◦ API 仕様書がメンテナンスされていない ◦ API 仕様書の変更に気付かない • API の実装を待たないとフロントの開発に着手できない • API のリクエストやレスポンスが想定していたものと違う ◦ 修正コストが発生
11 スキーマ駆動開発の出番です 💪 #readyfor_meetup
12 スキーマ駆動開発 スキーマとは? #readyfor_meetup • 定められた形式で記述したもの • Web API の仕様定義
◦ エンドポイント ◦ リクエストやレスポンスのデータ構造 ◦ 値の型やフォーマット
13 スキーマ駆動開発 スキーマ駆動開発とは? #readyfor_meetup Web API の開発者と利用者でスキーマ設計を行い スキーマを中心とした開発を行うこと
14 スキーマ駆動開発 開発の中心にスキーマがある 様々なツールを活用してこれを実現する #readyfor_meetup 仕様の相談 クライアントの 実装 モックサーバー の活用
ドキュメントの 生成 コードの生成 API の実装 スキーマ
15 スキーマ駆動開発 開発フローの違い #readyfor_meetup スキーマ駆動開発以前 設計 実装 実装 完成 完成
Web API 開発者 Web API 利用者 検証 実装を待つ 必要がある スキーマ駆動開発以降 完成 完成 Web API 開発者 Web API 利用者 スキーマ設計 検証 実装 実装 実装を待つ 必要がない
16 スキーマの定義 仕様の相談 クライアントの 実装 モックサーバー の活用 ドキュメントの 生成 コードの生成
API の実装 スキーマ #readyfor_meetup
17 スキーマ定義 OpenAPI #readyfor_meetup • 旧 Swagger Specification • Web
APIを記述するためのフォーマット • Open API Initiative により推進 • スキーマを JSON/YAML 形式で記述することができる • READYFOR では OpenAPI 3.0 を使用
18 スキーマ定義 OpenAPI #readyfor_meetup • /pets/{petId} へ GET リクエスト ◦
petId: 必須・string 型 • JSON 形式で 200 レスポンス ◦ id: 必須・integer 型で・int64 フォーマット ◦ name: 必須・string 型 ◦ tag: string 型
19 スキーマ定義 スキーマ定義の仕方 #readyfor_meetup • Swagger Editor ◦ スキーマを編集しながらプレビューが可能なエディタ •
Stoplight Studio ◦ スキーマを定義するための GUI エディタ ◦ Stoplight 社が提供 ◦ Swagger Editor と違い GUI のため OpenAPI のスキーマ定義の仕方知らなく ても編集することができる(OpenAPI 初心者に優しい) ◦ Git との連携やモックサーバーの統合など豊富な機能を備えている
20 スキーマ定義 Swagger Editor #readyfor_meetup
21 スキーマ定義 Stoplight Studio #readyfor_meetup
22 ドキュメントの自動生成 仕様の相談 クライアントの 実装 モックサーバー の活用 ドキュメントの 生成 コードの生成
API の実装 スキーマ #readyfor_meetup
23 ドキュメントの自動生成 Swagger UI #readyfor_meetup • OpenAPI のスキーマから見やすいドキュメントを生成することができる • Swagger
Editior のプレビュー • スキーマからドキュメントが生成されるので信頼できる
24 ドキュメントの自動生成 Swagger UI #readyfor_meetup
25 コードの自動生成 仕様の相談 クライアントの 実装 モックサーバー の活用 ドキュメントの 生成 コードの生成
API の実装 スキーマ #readyfor_meetup
26 コードの自動生成 OpenAPI Generator #readyfor_meetup • OpenAPI のスキーマから API クライアントなどのコードを生成することがで
きる • Swagger Codegen からフォークされコミュニティ主導で開発されている • 多くの言語・フレームワークをサポート
27 • openapi.yml ファイルを元に src/types/api ディレク トリに生成ファイルを出力 • READYFOR では
ジェネレーターとして typescript-fetch を使用 ◦ typescript-fetch 以外にも typescript-axios や typescript-angular、typescript-redux-query な ど様々存在する コードの自動生成 OpenAPI Generator #readyfor_meetup
28 コードの自動生成 API クライアントやモデル、リクエスト・レスポンスの型が生成される #readyfor_meetup
29 コードの自動生成 型安全 #readyfor_meetup • スキーマから自動で型が生成される ◦ リクエストやレスポンスの型を信頼できる ◦ 定型コードを記述するコストも減る
• スキーマが変更された際もビルドエラーで修正箇所を把握できる
30 コードの自動生成 ハマりどころ1 #readyfor_meetup tags を指定せずにスキーマを定義すると、API クラス名が自動で生成されてしまう
31 tags を指定してスキーマを定義すると、意図した API クラス名で生成できる コードの自動生成 ハマりどころ1 #readyfor_meetup
32 コードの自動生成 ハマりどころ2 #readyfor_meetup operationId を指定せずにスキーマを定義すると、 API クラスのメソッド名やリクエストデータの型名が自動で生成されてしまう
33 コードの自動生成 ハマりどころ2 #readyfor_meetup operationId を指定してスキーマを定義すると、意図した命名で生成できる
34 コードの自動生成 ハマりどころ3 #readyfor_meetup components/schema を使用せずにスキーマを定義すると、 InlineResponsXXX のようなレスポンスデータの型名が自動で生成されてしまう
35 コードの自動生成 ハマりどころ3 #readyfor_meetup components/schema を使用してスキーマを定義すると意図した型名で生成できる
36 モックサーバーの活用 仕様の相談 クライアントの 実装 モックサーバー の活用 ドキュメントの 生成 コードの生成
API の実装 スキーマ #readyfor_meetup
37 モックサーバーの活用 Stoplight Prism #readyfor_meetup • OpenAPI のスキーマ定義から API のモックサーバーを起動できる
◦ スキーマに基づいたエンドポイント・レスポンス ◦ API の実装を待たずに開発に着手することができる • Stoplight 社が提供 • Stoplight Studio にもモックサーバーとして統合されている
38 • openapi.yaml ファイルからモックサーバーを起動 • デフォルトではスタティックレスポンスを生成 ◦ 毎回同じデータをレスポンス ◦ スキーマに
Example が定義されていればそれをレ スポンスする ◦ スタティックレスポンスの生成条件がやや複雑 ▪ 詳しくはこちらを参照 • --dynamic/-d フラグを使用することでダイナミックレスポン スを生成 ◦ 毎回異なるデータをレスポンス モックサーバーの活用 Stoplight Prism #readyfor_meetup
39 • code ◦ 指定したステータスコードに応じてレスポンス • example ◦ スキーマに定義された Example
のキー名を指定す ることで、その Example をレスポンス • dynamic ◦ true を指定することでダイナミックレスポンスを有効 化 モックサーバーの活用 Prefer ヘッダーを渡すことでレスポンスの変更が可能 #readyfor_meetup
40 例えば「入力フォームの Submit ボタンを押して 422 エラーが レスポンスされたとき、エラーメッセージが表示されるか」など のテストが簡単にできる • cy.server
でバックエンドの呼び出しを待つ • onAnyRequest を使用してリクストヘッダーをカスタマイズ ◦ Prefer ヘッダーを追加 モックサーバーの活用 Cypress と相性が良い #readyfor_meetup
41 所感 #readyfor_meetup
42 所感 スキーマ駆動開発を実践してみてよかったこと #readyfor_meetup • API ドキュメントが信頼できる • TypeScript のコードが生成されるため型安全
• モックサーバーによる効率的・テスタブルな開発 • バックエンドエンジニアとも認識を合わせやすい ◦ OpenAPI のリポジトリ上の PR 上でやりとり ◦ 考慮漏れの発覚や要望などが発生した場合 PR を送る ◦ マージされればすぐに開発に着手できる
43 所感 スキーマ駆動開発を実践してみて辛いと感じたこと #readyfor_meetup • OpenAPI Generator によって生成されたコードで型エラー ◦ oneOf/allOf
を使用したスキーマ定義でよく発生する ◦ openapi-generator-cli の -g オプションで指定するジェネレーターを typescript-fetch から typescript-axios に変更すると正しいコードが生成できたりする…(逆もありそう)
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 所感 スキーマ駆動開発を実践する前に検討した方が良さそうなこと #readyfor_meetup • OpenAPI Generator によって生成された API クライアントを使用するか?それとも型定義のみを使
用するか? ◦ 生成された API クライアントを使用する場合、当然それに依存することになる ◦ 生成された API クライアントのコードをあらかじめ読んで、使用するか判断した方が良い • openapi-generator-cli の -g オプションで指定するジェネレーターをどれにするか? ◦ 型定義のみを使用する場合は、先に説明した出力される型定義との兼ね合いをみて決定した方 が良さそう
46 所感 スキーマ駆動開発を実践してみて重要だと感じたこと #readyfor_meetup • フロントエンドとバックエンド共にスキーマからコード生成すること • フロント側のみスキーマからコードを生成しても、スキーマと API の実装に乖離が発生する可能性が
高い • 最悪の場合、スキーマがメンテナンスされなくなる
47 スキーマ駆動開発はメリットがデメリットをはるかに上回ります 興味を持った方は是非実践してみてください 🙌 #readyfor_meetup
48 ご清聴いただきありがとうございました 🙇 #readyfor_meetup