先に要点をまとめると、このデザインファーストのプロセスはスプリントごとに次の流れで回します。

1. そのスプリントのAPI作業の担当を、バックエンドとフロントエンドから1人ずつ決める。
2. 2人でスプリントの要件に沿ってOpenAPIスキーマを書く（または更新する）。双方が納得するまでレビューする。
3. スキーマをリポジトリにコミットする。ここから先は、これがコントラクトになる。
4. コミットされたスキーマから、CIがモックサーバーを立てる。
5. フロントエンドはモックに対して開発し、その間にバックエンドが本物のエンドポイントを実装する。
6. 本物のサービスがデプロイされたら、そこから生成されたスペックを次のスプリントのスキーマの出発点にする。

きっかけ

#

発端はレトロスペクティブでした。APIの計画がいかに見えていないか、フィードバックは容赦なかった。バックエンドは要件を自分たちなりに解釈してエンドポイントを作り、フロントエンドは後からレスポンスの形を知り、ズレは統合の段階、つまり一番高くつくタイミングで発覚する。そこで出た提案が、両サイドを計画段階から巻き込み、OpenAPIスキーマをすべての土台にしようというものでした。

プロセス

#

毎週、バックエンドとフロントエンドから1人ずつ、計2人の代表を選びます。代表の仕事は、スプリントの要件を理解して、計画用のOpenAPIスキーマをそれに合わせることです。2人でスキーマをレビューし、合っていない部分を直していけば、作り始める前に、双方が何を作るのかを正確に把握できます。

修正が落ち着いたら、スキーマをリポジトリにコミットします。するとCI/CDがそのyamlからモックAPIを生成します。スプリントが終わったら、次のスプリントのAPI要件をまとめた新しいyamlを切って、同じサイクルを繰り返します。

ツールまわりのメモ

#

yamlの可視化にはSwagger Editorで十分です。ファイルをアップロードすれば、ちゃんとしたSwaggerドキュメントとして表示されます。

CI/CDパイプラインには、yamlを受け取ってモックサーバーを立てる仕組みが必要です。StoplightのPrismは広く使われている選択肢で、OpenAPI 3.1にも対応しています。

npm install -g @stoplight/prism-cli
prism mock openapi.yaml

これでスキーマ内のすべてのパスが http://127.0.0.1:4010 で提供され、スキーマの examples がそのままレスポンスとして返ってきます。たとえば GET /lists/10 なら、付録のサンプルのリストが返ります。コントラクトもきちんと守らせてくれます。例ではAPIキーを宣言しているので、X-API-Key ヘッダーのないリクエストには401が返ります。フロントエンドが作り込むべきなのは、まさにこの挙動です。コンテナの中で動かすときは、外からアクセスできるように -h 0.0.0.0 を付けてください。openapi-mockは、ランダムなデータでレスポンスを埋めてくれる、より軽量な選択肢です。

モックを立てる前にスキーマをリントしておくのもおすすめです。壊れたコントラクトがあればビルドが失敗するので、フロントエンドが混乱せずに済みます。Spectralは、1行のルールセットを置けば動きます。

npm install -g @stoplight/spectral-cli
echo 'extends: ["spectral:oas"]' > .spectral.yaml
spectral lint openapi.yaml

最後に、このスキーマはあくまで計画用の成果物です。本物のAPIがデプロイされたら、各サービスが自分のopenapi.jsonを生成するべきで、それをダウンロードして次の計画に再利用します。

なぜやる価値があるのか

#

議論が一番安い場所に移動するからです。スキーマを書いている段階でフロントとバックのエンジニアが同席していれば、誤解はコードになる前に捕まります。API要件はスプリント途中で再交渉されるのではなく一度で合意されるし、モックサーバーのおかげでフロントエンドは待たずにすぐ着手できる。重要な細部の見落としもぐっと減ります。なにしろ2組の目と、書面になった契約をすり抜けなければならないので。

革命的な話はひとつもありません。ただ、機械がモックとして返せるくらい具体的なところまで計画を落とし込んだだけです。そして結局のところ、計画に必要な具体性とは、ちょうどそのくらいなのだと思います。

付録A - yamlの例

#

openapi: 3.1.0
info:
  title: MyApp Sprint 3
  description: Planning schema for sprint 3. Drives the mock server only.
  version: 0.3.0
servers:
  - url: https://api-mock.example.com/v1
tags:
  - name: lists
    description: Saved lists feature (PROJ-123)
security:
  - api_key: []
paths:
  /lists:
    get:
      tags: [lists]
      summary: Return the current user's saved lists
      operationId: getLists
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/List'
  /lists/{listId}:
    get:
      tags: [lists]
      summary: Find a list by ID
      operationId: getListById
      parameters:
        - name: listId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        '404':
          description: List not found
components:
  schemas:
    List:
      type: object
      required: [id, title]
      properties:
        id:
          type: integer
          format: int64
          examples: [10]
        title:
          type: string
          examples: [Weekend reading]
        itemCount:
          type: integer
          examples: [7]
  securitySchemes:
    api_key:
      type: apiKey
      name: X-API-Key
      in: header

待ちのゲーム

#

従来のフローは直列です。バックエンドがAPIを設計・実装し、エンドポイントが実際に動くようになってから、フロントエンドが統合を始める。バックエンドの遅れはすべてフロントエンドのカレンダーに直撃しますし、リリース日が載っているのはたいていフロントエンドのカレンダーです。

コードより先にコントラクト

#

スキーマファーストのフローでは、両者がほぼ同時に走り出せます。コードが1行も存在しない段階で、APIの構造をOpenAPIスキーマに書き出します。すべてのエンドポイント、リクエストとレスポンスのモデル、認証方式、エラーコード。このドキュメントが、フロントエンドとバックエンドの間の契約書になります。

見返りはすぐに現れます。作る前に、全員が同じ形で機能を理解できる。バックエンドが実装中でも、フロントエンドはUIを作り始められる。合意済みの唯一の情報源を更新すればいいので、変更も速く回る。さらにスキーマから直接モックサーバーを生成できるので、本物のエンドポイントがひとつもない段階からフロントエンドのテストが始められます。

実際の回し方

#

1. 要件を集める。これは何を作るときでも同じです。
2. スキーマを設計する。エンドポイント、リクエスト／レスポンスモデル、認証、エラーコード。
3. フロントとバックの両方でレビューする。コントラクトが本領を発揮するのはここです。
4. モックサーバーを生成し（SwaggerでもPostmanでも可能です）、フロントエンドはそれに対して統合を進める。
5. バックエンドは同じスキーマに沿って本物のエンドポイントを実装する。
6. 出来上がったものからモックを本物に差し替え、契約が守られているか継続的にテストする。
7. 会話を続ける。スキーマは生きたドキュメントであって、石版ではありません。

引っかかりどころ

#

タダではありません。しっかりしたスキーマを前もって書くには、それなりの時間がかかります。要件が変われば先にスキーマを直す必要があり、その波紋は両チームに及びます。そして全員が、OpenAPIと周辺ツールについて最低限の土地勘を持っている必要があります。

それでも、この先行投資が、防いでくれる統合の混乱に負けたところを見たことがありません。フロントエンドは初日から動き出せますし、議論はビルドが壊れてからではなく、ドキュメントの上で起きるようになります。