これまで見てきた中で一番確実にスケジュールを殺すのは、難しいエンジニアリングではありません。「もうすぐできる」エンドポイントを、フロントエンドがひたすら待っている状態です。職場で落ち着いた解決策は地味ですが効きます。コードを書く前に、まずOpenAPIでAPIコントラクトに合意することです。
待ちのゲーム#
従来のフローは直列です。バックエンドがAPIを設計・実装し、エンドポイントが実際に動くようになってから、フロントエンドが統合を始める。バックエンドの遅れはすべてフロントエンドのカレンダーに直撃しますし、リリース日が載っているのはたいていフロントエンドのカレンダーです。
コードより先にコントラクト#
スキーマファーストのフローでは、両者がほぼ同時に走り出せます。コードが1行も存在しない段階で、APIの構造をOpenAPIスキーマに書き出します。すべてのエンドポイント、リクエストとレスポンスのモデル、認証方式、エラーコード。このドキュメントが、フロントエンドとバックエンドの間の契約書になります。
見返りはすぐに現れます。作る前に、全員が同じ形で機能を理解できる。バックエンドが実装中でも、フロントエンドはUIを作り始められる。合意済みの唯一の情報源を更新すればいいので、変更も速く回る。さらにスキーマから直接モックサーバーを生成できるので、本物のエンドポイントがひとつもない段階からフロントエンドのテストが始められます。
実際の回し方#
- 要件を集める。これは何を作るときでも同じです。
- スキーマを設計する。エンドポイント、リクエスト／レスポンスモデル、認証、エラーコード。
- フロントとバックの両方でレビューする。コントラクトが本領を発揮するのはここです。
- モックサーバーを生成し（SwaggerでもPostmanでも可能です）、フロントエンドはそれに対して統合を進める。
- バックエンドは同じスキーマに沿って本物のエンドポイントを実装する。
- 出来上がったものからモックを本物に差し替え、契約が守られているか継続的にテストする。
- 会話を続ける。スキーマは生きたドキュメントであって、石版ではありません。
引っかかりどころ#
タダではありません。しっかりしたスキーマを前もって書くには、それなりの時間がかかります。要件が変われば先にスキーマを直す必要があり、その波紋は両チームに及びます。そして全員が、OpenAPIと周辺ツールについて最低限の土地勘を持っている必要があります。
それでも、この先行投資が、防いでくれる統合の混乱に負けたところを見たことがありません。フロントエンドは初日から動き出せますし、議論はビルドが壊れてからではなく、ドキュメントの上で起きるようになります。