OpenAPIを利用してWebアプリケーションの開発プロセスを効率化した話

エクストーンの豊田です。Webアプリケーションの開発においてバックエンドチームがAPIを作成し、フロントエンドチームがそのAPIを利用してシステムを構築を行うような開発プロセスが私たちのチームでは頻繁に行われています。その中で、OpenAPIを積極的に活用しているプロジェクトの事例を紹介したいと思います。OpenAPIの定義を作成することで得られる具体的なメリットと、実際の活用方法について共有したいと思います。

OpenAPIとは

OpenAPIはRESTful APIを記述するための標準仕様です。JSONまたはYAML形式でAPIの仕様を定義することで、API設計の一貫性を確保し、様々なツールによる自動化が可能になります。

仕様を厳密に定義することで、チーム間でAPIに対する理解の齟齬がなくなるというメリットが大きいですが、その他、OpenAPIを利用した以下のようなプロセスの自動化によって、私たちのプロジェクトで大きな効果をもたらしています。

ドキュメントの自動生成
モックサーバーの作成
クライアントライブラリの自動生成

それぞれについて、具体的な実装方法とともに解説します。

1. ドキュメントの自動生成（Redoc）

APIドキュメントの作成と維持は、開発者にとって悩ましい作業です。特に頻繁に開発・更新が行われるプロジェクトでは実装とドキュメントが乖離していくことが頻繁に発生します。OpenAPIを使えば、仕様書からドキュメントを自動生成できるため、APIの仕様をOpenAPIで定義するという最低限のルールさえ徹底しておけば、ドキュメントはその仕様に追従して常に最新に保つことが出来ます。

Redocを使ったドキュメント生成

Redocは、OpenAPIの定義ファイルから美しく使いやすいドキュメントを生成するツールです。以下の手順で簡単に導入できます。

まず、OpenAPIの定義ファイル（openapi.yaml）を作成します：

openapi: 3.0.0
info:
  version: 1.0.0
  title: サンプルAPI
  description: これはサンプルAPIのドキュメントです
paths:
  /users:
    get:
      summary: ユーザー一覧を取得するAPI
      responses:
        '200':
          description: 成功時のレスポンス
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 1
                    name:
                      type: string
                      example: "山田太郎"

次に、Redocを使ってHTMLドキュメントを生成します：

# Redoc CLIをインストール
$ npm install -g redoc-cli

# HTMLファイルを生成
$ redoc-cli bundle openapi.yaml --output docs.html

開発中に継続的にドキュメントを確認したい場合は、サーバーモードが便利です。

$ redoc-cli serve openapi.yaml --watch

-watchオプションを付けることで、ファイルの変更を検知して自動的にドキュメントが更新されます。これにより、仕様変更の度にコマンドを実行する手間が省けます。

メリット

常に最新のドキュメントを維持できる
美しく見やすいインターフェース
エンドポイント、パラメータ、レスポンスなどが整理されて表示される
HTML形式のため、S3やGitHub Pagesなどで簡単に公開可能

2. モックサーバーの作成（Prism）

フロントエンド開発とバックエンド開発を並行して進めたい場合、バックエンドの開発が追いついておらず、フロントエンド側が実際にAPIをリクエストして開発をすることが出来ないことが発生します。この事態を回避するためには、仕様通りの仮の値を返すAPIのモックサーバーを作成することがあります。Prismを利用することで、OpenAPIの定義からモックサーバーを簡単に作成できます。

Prismを使ったモックサーバーの作成

Prismは、OpenAPIドキュメントに基づいてHTTPモックサーバーを生成するオープンソースツールです。以下のようなpackage.jsonを利用することで、モックサーバーを起動することが出来ます。

{
  "name": "prism-test",
  "scripts": {
    "prism": "prism mock ./openapi.yaml"
  },
  "devDependencies": {
    "@stoplight/prism-cli": "^5.12.0"
  }
}

OpenAPIの定義に複数のレスポンス例を用意しておけば、Preferヘッダーを使って異なるレスポンスを切り替えることができます。

# openapi.yaml（複数レスポンス例）
paths:
  /api/users:
    get:
      summary: ユーザー一覧を取得
      responses:
        '200':
          description: 成功
          content:
            application/json:
              examples:
                EmptyUserResponse:
                  value:
                    users: []
                ManyUserResponse:
                  value:
                    users:
                      - id: 1
                        name: "John Doe"
                        mailAddress: "john.doe@example.com"
                      - id: 2
                        name: "Jane Doe"
                        mailAddress: "jane.doe@example.com"

上記の package.json が存在するディレクトリで以下のコマンドを実行することで、モックサーバーを起動することが出来ます。

# 依存関係のインストール
$ npm install

# Prismサーバーの起動
$ npm run prism

# モックサーバーへリクエスト
$ curl -XGET http://localhost:4010/api/users 

# 特定の例を指定
$ curl -H "Prefer: example=ManyUserResponse" http://localhost:4010/api/users

メリット

バックエンド実装前にフロントエンド開発を進められる
異なるシナリオやエラーケースのテストが容易
設計段階から実際の動作確認ができ、早期にフィードバックを得られる
リクエストとレスポンスの検証により、仕様との整合性を確保できる

3. クライアントライブラリの自動生成（openapi-zod-client）

TypeScriptプロジェクトでは、APIクライアントの実装と型定義の維持が課題となります。openapi-zod-clientを使えば、OpenAPIの定義から型安全なAPIクライアントを自動生成できます。

openapi-zod-clientの使用方法

openapi-zod-clientは、OpenAPIの定義からZodiosベースのTypeScriptクライアントを生成するツールです：

# インストール
$ npm install -D openapi-zod-client

# クライアント生成
$ npx openapi-zod-client "./openapi.yaml" -o "./src/api/client.ts"

生成されたクライアントは、zodを使った型チェックとランタイムバリデーションを提供します。以下は使用例です。

// 生成されたクライアントのインポート
import { api } from './api/client';

// 型安全なAPI呼び出し
async function fetchUsers() {
  const response = await api.getUsers();

  // responseは型付けされている
  const users = response.data;

  // TypeScriptの型チェックが効く
  users.forEach(user => {
    console.log(`Name: ${user.name}, ID: ${user.id}`);
  });
}