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とAxiosPromiseの間で 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