このシリーズの最初の記事で、「コードを書く前にOpenAPIのコントラクトに合意しよう」という話をしました。今回はそのコントラクトを実際に「元が取れるもの」にしてくれるツールの話です。

フロントエンドのAPIレイヤーを手書きする作業は、楽しいと公言する人がいない類の仕事です。バックエンドのドキュメントから型を書き写し、40回目の同じリクエストラッパーを書き、3週間後に誰かがフィールド名を変えて、呼び出しの半分が静かに壊れる。Orvalはこの仕事そのものを消してくれます。OpenAPIスペックを指定すれば、クライアントコードを生成してくれるのです。全エンドポイント分の型付き関数、コントラクトに正確に一致するモデル、そしてバックエンドが存在する前から開発に使えるモック。

フロントエンドチームが気に入る理由

#

過小評価されがちなのがモック生成です。スペックに合意した時点で、フロントエンドは偽のサーバーを立てて、UI全体をそれに向かって作り込めます。永遠に「もうすぐできます」のエンドポイントを待つ必要はありません。本物のバックエンドができたら、クライアントの向き先を変えるだけで、だいたいそのまま動きます。両側が同じドキュメントから作られているからです。

もうひとつの利点は、退屈なコードが「構造的に正しい」状態になることです。手書きのリクエストボディでフィールド名を打ち間違える人はいなくなります。そもそも手書きのリクエストボディを書く人がいなくなるので。

バックエンドチームにも嬉しい理由

#

スペックが唯一の情報源になると、日々の会話が変わります。「このエンドポイントって何を返すんでしたっけ？」というチャットのスレッドの代わりに、フロントエンドは生成された型を読めばいい。バックエンド開発者は割り込まれる回数が減り、フィードバックは早く届くようになります。フロントエンドがモック相手に作ってみて「このAPI、使いにくいな」と感じたら、それが分かるのは本番投入後ではなく、まだ変更が安上がりなうちです。

ワークフローへの組み込み方

#

けっして凝ったことはしていません。バックエンドがスペックを提案し、両チームでレビューし、フロントエンドはOrvalでクライアントとモックを生成して作り始め、バックエンドは同じコントラクトに沿って本物を実装する。スペックが変わったら両側で再生成すれば、何が壊れたかはコンパイラが正確に教えてくれます。この最後の部分こそが本質です。フロントエンドとバックエンドのズレが、本番のバグではなくコンパイルエラーになるのです。

セットアップ

#

まずは開発用の依存関係としてインストールします。生成されたコードがimportするパッケージも一緒に入れておきましょう。React Queryのフックとモックを使うなら、TanStack Query、MSW、Fakerです。

npm install --save-dev orval msw @faker-js/faker
npm install @tanstack/react-query

次に、プロジェクトのルートにorval.config.tsを置きます。Orval公式ドキュメントの例とほぼ同じものです。

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: './openapi.yaml', // a path or a URL
    },
    output: {
      mode: 'single',
      target: './src/api/petstore.ts',
      schemas: './src/api/model',
      client: 'react-query',
      httpClient: 'fetch',
      mock: true, // MSW handlers plus Faker data
      override: {
        fetch: { includeHttpResponseReturnType: false },
      },
    },
  },
});

何が生成されるかはclientで決まります。素のfetchやaxiosの関数、React Query・Vue Query・Svelte Query・SWR用のフック、Angularのサービス、Zodのスキーマなどです。includeHttpResponseReturnType: falseの行は、fetchクライアントが{ data, status }ではなくレスポンスボディそのものを返すようにする設定で、コンポーネント側が欲しいのはたいていこちらです。

コマンドを誰も覚えなくて済むように、scriptsに登録しておきます。

{
  "scripts": {
    "api": "orval"
  }
}

npm run apiでフックとモデルが書き出されます。あとはコンポーネントから普通のReact Queryのフックと同じように使うだけで、型は最初から埋まっています。

import { useListPets } from './api/petstore';

export function PetList() {
  const { data: pets, isLoading } = useListPets();
  if (isLoading) return <p>Loading…</p>;
  return (
    <ul>
      {pets?.map((pet) => <li key={pet.id}>{pet.name}</li>)}
    </ul>
  );
}

スペックでフィールド名を変えてnpm run apiをもう一度実行すれば、pet.nameを使っている箇所が全部赤くなります。上で書いたズレのチェックがこれで、実行コストはゼロです。

モックを相手に開発する

#

mock: trueにすると、Orvalはエンドポイントごとに、レスポンスのスキーマどおりの形をしたFakerのデータを返すMSWのリクエストハンドラーと、それらをまとめて返す関数も書き出します。そのリストを、ブラウザならMSWのsetupWorkerに、テストならsetupServerに渡せば、アプリは最初からコントラクトに一致した偽のバックエンドを相手に動きます。各ハンドラーは上書き用の値も受け取れるので、テストで特定のペイロードや空のリスト、エラー状態を返したいときも、誰かがフィクスチャを手書きする必要はありません。

フロントエンドが初日から作業を始められるのは、この部分のおかげです。モックは誰かが別途メンテナンスしなければならない成果物ではありません。クライアントと同じスペックから毎回再生成されるので、スペックに置いていかれようがないのです。

Orvalとopenapi-generator、openapi-typescript、Hey APIの比較

#

どれもOpenAPIスペックから出発しますが、どこまで生成するかが違います。

型だけで足りるなら、openapi-typescriptが一番軽くて、文句のつけようがありません。openapi-generatorが真価を発揮するのは、1つのスペックから複数の言語向けにコードを生成しなければならないときです。TypeScriptの出力もちゃんと動きますが、読んでいると、まずJava向けに書かれたものだという感触があります。OrvalとHey APIのどちらにするかは、ほぼ好みと、どちらの出力コードを読みたいか次第です。私がOrvalを使い続けているのは、フックと同じ1回の実行でモックも出てくるからで、2つのチームの働き方を変えたのはまさにこの機能でした。

派手なツールではありません。ただ、チーム間の言い争いをひとつのカテゴリごと静かに消してくれる。それと引き換えなら、私はいつでも喜んで使います。

待ちのゲーム

#

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

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

#

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

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

実際の回し方

#

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

引っかかりどころ

#

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

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

光復節（8月15日）は、1945年に日本の植民地支配が終わったことを記念する韓国の祝日です。Zdogは、<canvas>やSVGに3Dっぽいイラストを描くための小さなJavaScriptライブラリです。図形は実際に3D空間に置かれていて3Dの物体のように回転しますが、描かれるのは平面の図形なので、3Dレンダリングというより、回して見られるフラットなイラストに近い見た目になります。旗のようなシンプルなものにはちょうどいい道具です。

Zdogの最小限の例

#

図形2つ、ドラッグで回転、そしてアニメーションのループです。

<canvas class="zdog-canvas" width="240" height="240"></canvas>
<script src="https://unpkg.com/zdog@1/dist/zdog.dist.min.js"></script>
<script>
  const illo = new Zdog.Illustration({
    element: '.zdog-canvas',
    dragRotate: true, // drag to turn the scene
  });

  // a square, pushed back
  new Zdog.Rect({
    addTo: illo,
    width: 80,
    height: 80,
    translate: { z: -30 },
    stroke: 8,
    color: '#0047a0',
  });

  // a filled circle, pulled forward
  new Zdog.Ellipse({
    addTo: illo,
    diameter: 60,
    translate: { z: 30 },
    stroke: 8,
    color: '#cd2e3a',
    fill: true,
  });

  function animate() {
    illo.rotate.y += 0.02;
    illo.updateRenderGraph();
    requestAnimationFrame(animate);
  }
  animate();
</script>

図形はaddToでシーンに追加します。3Dらしさを生んでいるのはtranslate.zで、シーンを回すと円が四角形の前に回り込んできます。updateRenderGraph()が全体を更新して描き直すので、ループの中で呼んでいます。

公式ドキュメント

#

https://zzz.dog/

使ったコードはCodePenで見られます。

作ってみたもの

#

セットアップの手順をまとめておきます。

そもそもなぜSASSなのか

#

素のCSSは、ページ数が少し増えただけで散らかり始めます。SASSなら変数・ネスト・ミックスイン・関数が使えるので、色や共通のレイアウト定義をあちこちにコピペせず、一箇所にまとめられます。そしてHugoユーザーにとって一番うれしいのは、Hugo PipesがSCSSをそのままコンパイルしてくれること。別のビルドツールもウォッチャースクリプトも要りません。

作業中に開いておくと便利なページはこの2つです。

• SASSのドキュメント
• HugoのSCSS/SASSサポートのドキュメント

セットアップ

#

1. assetsディレクトリを用意する

#

Hugoはプロジェクトのルートにあるassetsフォルダを見に行くので、そこに作成（または移動）します。resourcesフォルダの中に置きたい場合は、config.tomlでHugoに場所を教えてあげます。

assetDir = "resources/assets"

2. sassフォルダを作る

#

assetsの中にsassというフォルダを作ります。SCSSファイルはここに置きます。

3. エントリーポイントを追加する

#

sassフォルダの中にmain.scssを作成します。Hugoがコンパイルするのはこのファイルなので、動作確認を兼ねて少しSCSSを書いておきましょう。

// assets/sass/main.scss

// 変数
$primary-color: #3498db;

// ミックスイン
@mixin center {
  display: flex;
  justify-content: center;
  align-items: center;
}

// スタイル
body {
  font-family: Arial, sans-serif;
  background-color: $primary-color;
}

h1 {
  @include center;
  color: white;
}

4. テンプレートに組み込む

#

head.htmlパーシャルで、コンパイル済みスタイルシートを読み込んでminifyします。

{{ $style := resources.Get "sass/main.scss" | resources.ToCSS | resources.Minify }}
<link rel="stylesheet" href="{{ $style.Permalink }}">

ここのファイル名が、実際のエントリーポイント（main.scss）と一致しているかだけ確認してください。

スタイルの分割

#

サイトが育ってきたら、SCSSをパーシャルに分割してmain.scssからインポートします。

// assets/sass/_variables.scss
$primary-color: #3498db;

// assets/sass/_mixins.scss
@mixin center {
  display: flex;
  justify-content: center;
  align-items: center;
}

// assets/sass/main.scss
@import "variables";
@import "mixins";

body {
  background-color: $primary-color;
}

h1 {
  @include center;
  color: white;
}

本当にこれだけです。4ステップで、あとはビルドのたびにHugoがスタイルを再コンパイルしてくれます。アセットパイプラインと格闘する覚悟で臨んだのに、拍子抜けするほどあっさり動きました。