Upgrade to Pro — share decks privately, control downloads, hide ads and more …

OpenAPIでチーム開発を加速させる

Avatar for Yusuke Mizuno Yusuke Mizuno
May 22, 2024
500

 OpenAPIでチーム開発を加速させる

2024/05/22 フロントエンドLT会 - vol.9の登壇資料です
https://rakus.connpass.com/event/316560/

Avatar for Yusuke Mizuno

Yusuke Mizuno

May 22, 2024
Tweet

Transcript

  1. 嬉しい状態 🔥 実装と仕様が乖離している 🔥 メンテされないまま放置 💀 🔥 バージョニングなんて知らない 👊 最新版が正義

    🔥 ドキュメント?コード見ればわかるじゃん (笑) 👉 ドキュメントが実装と一致している (メンテされている) 👉 APIと同じくバージョニングが行われている 👉 ドキュメントをコードとして表現することが可能である
  2. フロントエンド開発におけるAPIドキュメントの役割 1. どのエンドポイントに対して 2. どのような操作を行うもので (GET, POST, PATCH, PUT, DELETE…)

    3. リクエストで何を投げたら 4. レスポンスで何が返ってくるか (+ エラーは何が発生し得るか ) を知ることができれば OK💡
  3. • 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
  4. • 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 👈
  5. • OpenAPIファーストな開発フロー • バックエンド / フロントエンドで言語仕様が異なる ◦ バックエンド: Kotlin, フロントエンド:

    TypeScript みたいなケース ◦ でもコード生成のツールチェインは揃えておきたい • 痒いところに手を届かせてくれそうなmustache • 捨てやすさ ◦ アプリケーションコードのノイズの少なさ => 実装と疎結合 ◦ パッケージ化の容易さ OpenAPI Generatorを選ぶ理由
  6. Reactプロジェクトの例 OpenAPI GitHub Packages (npm registry) React Project # クライアントコードの生成

    + publish $ openapi-generator-cli generate $ npm publish # プロジェクトに packageを入れる $ npm install generated-package
  7. コード生成の嬉しいところ • クライアントコードとOpenAPIが完全同期 🔄 ◦ どのバージョンでどこが変更されたのかコードレベルで追える ◦ OpenAPI / 生成したコードもGitHubでRelease/Tags管理

    • さらば手作業 👋 ◦ API仕様書のインターフェイス定義をそのままコードに写経する必要無し ◦ typo, required/nullable漏れのようなヒューマンエラーとは無縁 • OpenAPIの内容が正 ✨ ◦ 言語仕様を細かく気にする必要が無い undefined/null/blank ⇔ required/nullable/minLength:1 みたいなやつ ◦ REST APIを正しく設計する文化が自然と定着する
  8. 機能に関わるほぼ全てのinterfaceがOpenAPIに依存する • extends, Pick, Omitは無限にあるのに、元の型はプロジェクト内で定義されない (node_modulesの *.d.tsを参照するから) • 元の型に変更が入る =>

    その型を拡張している型も... 👎 ソースコード全体の見通しが悪くなる 👎 OpenAPI依存の型を使用する箇所の修正に時間がかかる
  9. 「実装を中断しなくていい」は正義 💪 OpenAPIの更新を取り込む + packageのpublish packageのバージョンを上げる + トランスパイルエラーを回避するための暫定修正 暫定修正した箇所の対応 •

    コンポーネントの実装に影響しない • 「一箇所変わったら全部壊れる」を回避できる • OpenAPI ⇔ Form ⇔ UIの型の乖離は HttpRequestメソッドで吸収できる
  10. • OpenAPIはバックエンド / フロントエンドを並行で開発するために必要な共通資産 実装と同等にメンテナンスされるべき • バックエンド / フロントエンドの分離開発において、Docs to

    Code / Code to Docs のような方法は有効 • REST APIとUIで、interfaceは別定義の方が嬉しい場面もある。開発フェーズ・チー ム構成に合わせてやり方を変えていくのも大事 まとめ