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でチーム開発を加速させる
Search
Yusuke Mizuno
May 22, 2024
1
500
OpenAPIでチーム開発を加速させる
2024/05/22 フロントエンドLT会 - vol.9の登壇資料です
https://rakus.connpass.com/event/316560/
Yusuke Mizuno
May 22, 2024
Tweet
Share
Featured
See All Featured
The Art of Programming - Codeland 2020
erikaheidi
54
13k
Put a Button on it: Removing Barriers to Going Fast.
kastner
60
3.9k
What’s in a name? Adding method to the madness
productmarketing
PRO
23
3.5k
JavaScript: Past, Present, and Future - NDC Porto 2020
reverentgeek
50
5.5k
Music & Morning Musume
bryan
46
6.6k
Making Projects Easy
brettharned
116
6.3k
Exploring the Power of Turbo Streams & Action Cable | RailsConf2023
kevinliebholz
34
5.9k
Site-Speed That Sticks
csswizardry
10
690
Statistics for Hackers
jakevdp
799
220k
Building an army of robots
kneath
306
45k
Visualizing Your Data: Incorporating Mongo into Loggly Infrastructure
mongodb
46
9.6k
Done Done
chrislema
184
16k
Transcript
OpenAPIでチーム開発を加速させる 株式会社ラクス 水野 友輔 2024/05/22 フロントエンドLT会 - vol.9
APIドキュメントって書いていますか? 🤔
あるある 🔥 実装と仕様が乖離している 🔥 メンテされないまま放置💀 🔥 バージョニングなんて知らない 👊 最新版が正義 🔥
ドキュメント?コード見ればわかるじゃん(笑)
嬉しい状態 🔥 実装と仕様が乖離している 🔥 メンテされないまま放置 💀 🔥 バージョニングなんて知らない 👊 最新版が正義
🔥 ドキュメント?コード見ればわかるじゃん (笑) 👉 ドキュメントが実装と一致している (メンテされている) 👉 APIと同じくバージョニングが行われている 👉 ドキュメントをコードとして表現することが可能である
フロントエンド開発におけるAPIドキュメントの役割 1. どのエンドポイントに対して 2. どのような操作を行うもので (GET, POST, PATCH, PUT, DELETE…)
3. リクエストで何を投げたら 4. レスポンスで何が返ってくるか (+ エラーは何が発生し得るか ) を知ることができれば OK💡
👉 REST APIドキュメントのフォーマット そのためのOpenAPI Specification (旧: Swagger) TypeScriptっぽく書けるTypeSpecが最近話題
ドキュメントとコードを等しくメンテナンスする
• OpenAPI Generator • Kiota • aspida • openapi-typescript •
openapi-zod-client etc… • zod-to-openapi • ts-rest (zod-openapi) • TypeDoc etc… Docs to Code Code to Docs
• OpenAPI Generator • Kiota • aspida • openapi-typescript •
openapi-zod-client etc… • zod-to-openapi • ts-rest (zod-openapi) • TypeDoc etc… Docs to Code Code to Docs 👈
OpenAPITools/openapi-generatorについてざっくり • OpenAPI(yaml/json)からコード・ドキュメント・ス タブサーバの生成が可能 • nodeで利用可能なラッパーライブラリ (openapi-generator-cli)が提供されている • サポートしている言語・フレームワークが豊富で カスタマイズ(mustache)も可能
• OpenAPIファーストな開発フロー • バックエンド / フロントエンドで言語仕様が異なる ◦ バックエンド: Kotlin, フロントエンド:
TypeScript みたいなケース ◦ でもコード生成のツールチェインは揃えておきたい • 痒いところに手を届かせてくれそうなmustache • 捨てやすさ ◦ アプリケーションコードのノイズの少なさ => 実装と疎結合 ◦ パッケージ化の容易さ OpenAPI Generatorを選ぶ理由
OpenAPIがクライアントコードになるまで
Reactプロジェクトの例 OpenAPI GitHub Packages (npm registry) React Project # クライアントコードの生成
+ publish $ openapi-generator-cli generate $ npm publish # プロジェクトに packageを入れる $ npm install generated-package
これが...
こうなる 👀
importして使える👌
コード生成の嬉しいところ • クライアントコードとOpenAPIが完全同期 🔄 ◦ どのバージョンでどこが変更されたのかコードレベルで追える ◦ OpenAPI / 生成したコードもGitHubでRelease/Tags管理
• さらば手作業 👋 ◦ API仕様書のインターフェイス定義をそのままコードに写経する必要無し ◦ typo, required/nullable漏れのようなヒューマンエラーとは無縁 • OpenAPIの内容が正 ✨ ◦ 言語仕様を細かく気にする必要が無い undefined/null/blank ⇔ required/nullable/minLength:1 みたいなやつ ◦ REST APIを正しく設計する文化が自然と定着する
おしまい 🎉 ...とはならず
UI Component / Formで扱う型との乖離
機能に関わるほぼ全てのinterfaceがOpenAPIに依存する • extends, Pick, Omitは無限にあるのに、元の型はプロジェクト内で定義されない (node_modulesの *.d.tsを参照するから) • 元の型に変更が入る =>
その型を拡張している型も... 👎 ソースコード全体の見通しが悪くなる 👎 OpenAPI依存の型を使用する箇所の修正に時間がかかる
OpenAPIの更新と機能実装が非同期 Publishしたよ〜 < すぐにバージョン上げたい < 型イカれるからちょっと待って 💦 < mainにマージされるまで実装しません
🙈 ブランチ/PR毎に状況が異なる
開発を回し続けるための工夫
最初に壊れるのはどこ? 1. ComponentProps, query, mutationが OpenAPIのinterfaceに依存する 🔥コンポーネントのType Error 2. Promise<T>とAxiosPromise<T>の間で
interfaceの整合性を取る 🔥HttpRequestメソッドのType Error
HttpRequest / Responseのinterfaceを分離する プロジェクトで必要な型を定義 パッケージから型をimportする箇所を制限 +
“一旦” 壊れてもいいところを決めておく
型の恩恵を最大限に受けよう msw, テストコードのfixtureも生成した型で縛れる
「実装を中断しなくていい」は正義 💪 OpenAPIの更新を取り込む + packageのpublish packageのバージョンを上げる + トランスパイルエラーを回避するための暫定修正 暫定修正した箇所の対応 •
コンポーネントの実装に影響しない • 「一箇所変わったら全部壊れる」を回避できる • OpenAPI ⇔ Form ⇔ UIの型の乖離は HttpRequestメソッドで吸収できる
• OpenAPIはバックエンド / フロントエンドを並行で開発するために必要な共通資産 実装と同等にメンテナンスされるべき • バックエンド / フロントエンドの分離開発において、Docs to
Code / Code to Docs のような方法は有効 • REST APIとUIで、interfaceは別定義の方が嬉しい場面もある。開発フェーズ・チー ム構成に合わせてやり方を変えていくのも大事 まとめ
素敵なスキーマ駆動開発ライフを 🎉
ちょいちょい登場していたリポジトリ https://github.com/hairihou/openapi-generator-example ※GitHub: QR (https://ohno.github.io/github-qr/)を使用しています 参考記事: https://zenn.dev/ohno/articles/295201bf0e64ce