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 Pragmatic Product Professional
lauravandoore
35
6.7k
How STYLIGHT went responsive
nonsquared
100
5.6k
4 Signs Your Business is Dying
shpigford
184
22k
Speed Design
sergeychernyshev
32
1k
Being A Developer After 40
akosma
90
590k
The Language of Interfaces
destraynor
158
25k
The Art of Delivering Value - GDevCon NA Keynote
reverentgeek
15
1.5k
Build your cross-platform service in a week with App Engine
jlugia
231
18k
10 Git Anti Patterns You Should be Aware of
lemiorhan
PRO
657
60k
The Straight Up "How To Draw Better" Workshop
denniskardys
234
140k
Intergalactic Javascript Robots from Outer Space
tanoku
271
27k
XXLCSS - How to scale CSS and keep your sanity
sugarenia
248
1.3M
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