QueryLift株式会社で開発を担当しているウルフ ジャスティンと申します。

API開発において、フロントエンドとバックエンドの仕様齟齬による手戻りや、API仕様書と実装の乖離、新機能追加時のドキュメント更新漏れなどの課題は多くの開発チームが直面する問題です。

私たちQueryLiftはOpenAPIを活用したSchema-First開発を導入することで、これらの課題を根本的に解決し、開発体験を大幅に改善することができています。

この記事では、実際にQueryLiftで導入したOpenAPI駆動開発の実装方法と、その過程で得られた学びをご紹介します。

従来のCode-First開発で感じていた課題

QueryLiftのサービス開発において、当初は一般的なCode-First開発を採用していました。つまり、まずバックエンドAPIを実装し、その後にAPIドキュメントを作成するという流れです。

しかし、この手法では以下のような課題に日常的に直面していました。

実装とドキュメントの乖離

最も深刻だったのは、実装後にドキュメントを作成するため、常に仕様と実装が乖離してしまうことでした。

弊社のようなスタートアップ企業においては、開発速度を重視するべくドキュメンテーションが後回しにされがちです。それにより、ドキュメントの陳腐化が大きな課題でした。

バックエンドAPI完成待ちのボトルネック

フロントエンド開発者は、バックエンドAPIが完成するまで実際の開発を進めることができず、モックデータでの開発に頼らざるを得ませんでした。

このため、フロントエンドとバックエンドの並行開発が困難で、全体的な開発スピードにボトルネックが生じていました。

口頭伝達による認識ズレ

新しいAPIエンドポイントの仕様について、SlackやMeetingでの口頭説明に頼ることが多く、細かな仕様について認識ズレが生じることがありました。

「このパラメータは必須でしたっけ？」「レスポンスの形式はどうなっていましたっけ？」といった確認作業が頻繁に発生していました。

OpenAPI Schema-First開発への転換決断

これらの課題を解決するため、私たちは開発手法を根本的に見直すことにしました。

なぜSchema-Firstに転換したのか？

従来の「実装→仕様書」の流れではなく、「仕様書→実装」への転換を行いました。

API仕様書を単なる「ドキュメント」ではなく、フロントエンドとバックエンド間の「契約書」として位置づけることで、以下のメリットを狙いました：

  • 事前合意による手戻り削減：実装前に仕様を確定することで、後からの大幅な変更を防ぐ
  • 並行開発の実現：仕様が確定した時点で、フロントエンドとバックエンドが同時に開発開始可能
  • 自動化による品質向上：仕様書から自動でコード生成することで、人的ミスを削減

特にopenAPIは、エコシステムが豊富なこと、swaggerにより非エンジニアとの仕様共有もしやすいことがあり、採用を決定しました。

QueryLift式：リポジトリ分離によるOpenAPI管理システム

OpenAPI導入にあたり、私たちは独自の管理システムを構築しました。その特徴は、「API仕様管理」と「実装」を完全に分離した2リポジトリ構成です。

リポジトリ分離のアーキテクチャ

API仕様管理リポジトリ

api-docs/
├── specs/
│   ├── paths/                    # APIパス定義
│   │   ├── auth.yaml
│   │   ├── users.yaml
│   │   └── ...
│   └── components/
│       └── schemas/              # データモデル定義
│           ├── common.yaml
│           ├── models.yaml
│           └── ...
├── merge-script.py              # paths/とcomponents/のファイルを統合しopenapi.yamlを生成するスクリプト
└── dist/
    └── openapi.yaml             # 統合された仕様書

分割管理を採用した理由

機能ごとの独立した管理とレビュー

新機能追加時に、関連するファイルのみを変更すれば良いため、レビューが容易になりました。また、機能の削除時も該当ファイルを削除するだけで済みます。

共通スキーマの効率的な再利用

エラーレスポンスやページネーション情報など、複数のAPIで共通利用するスキーマをcomponents/schemas/に配置し、$refで参照することで、重複を排除しました。

大規模APIでも見通しの良い構造

APIエンドポイントが増加しても、ディレクトリ構造により整理された状態を保つことができます。

自動化システムの仕組み

分割管理されたOpenAPIファイルを実用的にするため、以下の自動化を実装しました。

ファイル統合の自動化

分割されたYAMLファイルを1つの完全なOpenAPI仕様書に統合するスクリプト（merge-openapi.py）を作成しました。このスクリプトを実行すると、各ディレクトリのyamlファイルを結合し、dist/openapi.yamlに完全なAPI仕様書を生成します。

コード自動生成

統合されたOpenAPI仕様書から、OpenAPI Generatorを使ってGoのコードを自動生成します：

# 仕様書の統合（merge-openapi.pyの実行）
make merge

# コード生成
make generate

生成されるもの：

  • APIインターフェース定義
  • リクエスト/レスポンスの構造体
  • バリデーション
  • ルーティング

Schema-Firstによる開発ワークフローの変化

OpenAPI導入により、私たちの開発ワークフローは根本的に変化しました。

新しい開発フロー

1. API仕様設計

新機能開発は、まずOpenAPI仕様書の作成から始まります。実装の詳細ではなく、APIの外部インターフェースに集中して設計を行います。

2. 仕様レビューと合意

Swagger UIにより、エンジニアだけでなくプロダクトマネージャーなども含めて、視覚的に仕様を確認できます。この段階で仕様について十分に議論し、合意を形成することで、後の手戻りを大幅に削減できます。

3. 並行実装開始

仕様が確定した時点で、フロントエンドとバックエンドの実装を並行して開始できます：

  • バックエンド: コード生成 → 生成されたインターフェースを実装
  • フロントエンド: 型定義生成 → モックサーバーでの開発

4. 統合とテスト

生成されたコードにはバリデーション機能も含まれているため、OpenAPI仕様に準拠していないリクエスト/レスポンスを自動で検出できます。

実際に感じた改善点

事前の仕様合意により手戻りが大幅減少

従来は「とりあえず実装してみて、問題があったら修正」というアプローチでしたが、事前に仕様を確定することで、大幅な設計変更が後から発生することがほとんどなくなりました。

フロントエンド・バックエンドの並行開発が実現

最も大きな変化は、真の意味での並行開発が実現できたことです。フロントエンド開発者は、バックエンドAPIの完成を待つことなく、確定した仕様に基づいて開発を進めることができるようになりました。

チーム間のコミュニケーションコストが削減

「このAPIのレスポンス形式はどうなっていましたっけ？」といった確認作業が激減しました。常に最新のSwagger UIを参照すれば、すべての仕様を確認できるためです。

実装で工夫した技術的ポイント

実際の運用を通じて、以下の技術的な工夫を重ねてきました。

ファイル分割とスキーマ再利用

ファイル分割の基準を明確化し、チーム内で統一しました：

  • パス定義: 機能やリソース単位で分割
  • スキーマ定義: モデル単位で分割
  • 共通要素: 複数機能で使用するものは独立ファイル化

エラーレスポンスなど、共通で使用するスキーマは効率的に再利用できるよう設計しました：

# 共通エラースキーマ
ErrorResponse:
  type: object
  properties:
    error:
      type: string
    statusCode:
      type: integer
  required: [error, statusCode]

自動バリデーションとカスタムルール

生成されたコードには、OpenAPI定義に基づく自動バリデーション機能が含まれています。さらにビジネス固有のルールが必要な場合は、UseCase層で追加実装しています。

統一されたエラーハンドリング

全てのAPIエンドポイントで一貫したエラーレスポンス形式を採用し、フロントエンド側でのエラーハンドリングを統一しました。

まとめ - Schema-Firstが変えた開発文化

QueryLiftでのOpenAPIによるSchema-First開発導入を振り返ると、これは単なる技術的な変更ではなく、開発文化そのものを変革する取り組みでした。

最も大きな変化は、チーム全体の意識が「とりあえず実装してみる」から「まず設計を固める」に変わったことです。この変化により、後戻りが大幅に減り、より計画的で品質の高い開発が可能になりました。

OpenAPIの価値は、単なるドキュメント生成ツールではなく、フロントエンドとバックエンド、そしてプロダクトチーム全体を繋ぐ「共通言語」となることにあります。技術的な詳細を知らないメンバーも含めて、APIの仕様について同じレベルで議論できるようになったことは、期待以上の効果でした。

おわりに

現在、API開発での課題を感じているなら、OpenAPIによるSchema-First開発は有力な解決策の一つです。完璧なシステムを一度に構築する必要はありません。小さく始めて、チームに合った形で改善していけば、必ずその価値を実感できるはずです。