TL;DR
デザインファーストのアプローチとは、実装コードよりも前にAPI仕様書を作成し、その仕様書がモック、ドキュメント、テスト、クライアントスタブなど、その後のすべての開発を推進するということです。このワークフローをエンドツーエンドでサポートするプラットフォームを選択することで、コードとドキュメントの同期を保つという絶え間ない摩擦が解消されます。この記事では、デザインファーストのアプローチについて説明し、Apidogを完全なデザインファーストプラットフォームとして、優れたツールがどのようなものかを評価します。
ApidogApidogを無料で試す
はじめに
ほとんどの開発者は、コードファーストでAPIを構築することを学びます。ルートを記述し、いくつかのアノテーションを追加し、ジェネレーターを実行すると、ドキュメントが生成されます。これは機能します。機能しなくなるまでは。
ドキュメントはずれが生じます。アノテーションは古くなります。新しいエンジニアが応答フォーマットを変更しても、デコレーターの更新を忘れることがあります。半年後、ドキュメントにはAPIが文字列の配列を返すと書かれているのに、実際の応答はvalueフィールドを持つオブジェクトの配列を返す、ということが起こります。
デザインファーストはこの状況を逆転させます。仕様書が信頼できる唯一の情報源となります。コード、ドキュメント、モックはすべて仕様書から派生します。仕様書が変更されると、すべてが一緒に変更されます。なぜなら、すべてがそこから生成されたからです。
これは理論上の区別ではありません。デザインファーストを採用するチームは、統合時の予期せぬ問題が少なくなり、フロントエンド開発が高速化し（モックが初日から利用できるため）、ドキュメントが常に正確であると報告しています。なぜなら、ドキュメントは二次的な成果物ではないからです。
しかし、デザインファーストは、仕様書作成を実用的な速さで行えるツールを必要とします。仕様ツールでエンドポイントを定義するのに20分かかり、ルートハンドラーの記述に5分かかるようでは、誰も仕様ツールを使用しないでしょう。プラットフォームは、デザインファーストをコードファーストよりも速く、遅くなくする必要があります。
デザインファーストが実際に意味するもの
デザインファーストはテクノロジーではなく、ワークフローです。API開発の各段階でどのようなものかを見てみましょう。
コードを記述する前
APIデザインはOpenAPI仕様として定義されます。これには以下が含まれます。
- すべてのエンドポイントパスとHTTPメソッド
- リクエストパラメーターの定義（パス、クエリ、ヘッダー）
- POST/PUT/PATCHエンドポイントのリクエストボディスキーマ
- すべてのステータスコード（200、400、401、422、500）のレスポンススキーマ
- 認証要件
- フィールドの説明と例
この設計レビューで、命名、データ構造、エラー処理パターンなど、重要な決定のほとんどが行われます。
開発中
仕様書はモックサーバーに公開されます。フロントエンドエンジニアはモックに対して開発を行い、バックエンドエンジニアは仕様書を要件定義書として実装します。両チームは互いにブロックすることなく並行して作業します。
実装後
自動テストは、実際の実装が仕様書と一致していることを検証します。契約からの逸脱はテスト失敗となります。
要件が変更された場合
まず仕様書が更新されます。両チームはその変更をレビューします。モックは自動的に更新されます。テストは、更新された仕様に従わない実装を検知します。
デザインファーストプラットフォームに必要なもの
すべてのAPIツールがデザインファーストのワークフローをサポートしているわけではありません。以下に、対応しているツールと対応していないツールを分けるものを示します。
ビジュアルAPIエディタ
生のYAMLは、デザイン媒体としては貧弱です。ビジュアルエディタを使用すると、YAMLのインデントと格闘することなく、APIの構造とセマンティクスに集中できます。エディタは、有効なOpenAPIを生成し、スキーマの再利用（コンポーネント）をサポートし、リアルタイムで検証する必要があります。
OpenAPI検証
仕様書は、何かに使用される前に有効なOpenAPIである必要があります。インライン検証は、コード生成時やモック時ではなく、編集中に間違いを捕捉します。
仕様からの自動モック生成
仕様書を記述すれば、モックが得られます。追加のステップは不要です。モックは、スキーマからのフィールドタイプ、フォーマット、制約を尊重したデータを返す必要があります。これが並行開発を実用的にします。
現実的な例を含むドキュメントプレビュー
仕様書は、設計フェーズ中にステークホルダーと共有できる読みやすいドキュメントとしてレンダリングされる必要があります。非技術系のチームメンバーもそれを読んでフィードバックを提供できるべきです。
チームレビューワークフロー
デザインファーストは、仕様の変更をコードの変更と同じように扱います。誰かが変更を提案し、他のメンバーがそれをレビューし、承認または改訂されます。プラットフォームには、非同期コメント機能と変更追跡機能が必要です。
標準OpenAPIへのエクスポート
仕様書はポータブルである必要があります。標準OpenAPIとしてエクスポートし、コードジェネレーター、APIゲートウェイ、テストフレームワークなど、あらゆる下流ツールで使用できるべきです。
デザインファーストプラットフォームとしてのApidog
Apidogのアーキテクチャは、主要な成果物としての仕様を中心に構築されています。デザインタブ、モックサーバー、テストランナー、ドキュメントはすべて、同じ基盤となるAPI定義に接続されています。
ビジュアルOpenAPIエディタ
Apidogのデザインインターフェースは、フォームベースの編集を使用します。各エンドポイントは、パス、メソッド、パラメーター、リクエストボディ、レスポンスなどの構造化されたフォームです。スキーマフィールドは、タイプピッカー、説明エディタ、検証ルール、およびモックアノテーションで定義されます。
希望しない限り、YAMLを記述する必要はありません。Apidogは、仕様のYAMLまたはJSON表現を表示する生表示を提供し、必要に応じて直接編集できます。ビジュアルビューでの変更は生表示に同期され、その逆も同様です。
スキーマコンポーネントはファーストクラスです。UserProfileスキーマをコンポーネントセクションで定義します。あらゆるエンドポイントで$refを使用してそれを参照します。スキーマを一度変更すると、それを参照するすべてのエンドポイントに変更が反映されます。
リアルタイムドキュメントプレビュー
エンドポイントを設計すると、ドキュメントビューがリアルタイムで更新されます。設計インターフェースを離れることなく、公開されるドキュメントでエンドポイントがどのように表示されるかをプレビューできます。プレビューには、レンダリングされた説明、フィールドタイプと制約を含むスキーマテーブル、および応答例が表示されます。
設計フェーズ中に、プロダクトマネージャーやフロントエンドリーダーとドキュメントリンクを共有し、レビューを受けられます。彼らは何もインストールする必要はありません。
スマートモック：仕様から動作するモックへ
Apidogのデザイナーで新しいエンドポイントを保存すると、モックサーバーはすぐに利用可能になります。モックURLがインターフェースに表示されます。モックは、スキーマに基づいて応答データを生成します。
format: emailを持つ文字列フィールドは、有効なメールアドレスを返しますminimumとmaximumを持つ整数フィールドは、範囲内の値を返します- Enumフィールドは、ランダムに選択されたEnum値を返します
- ネストされたオブジェクトと配列は、ネストされたスキーマ構造に従います
$refコンポーネントは正しく解決され、モックされます
特定のシナリオに対してカスタムモックルールを設定することもできます。たとえば、パスパラメーターが0の場合は404を返す、特定のクエリパラメーター値に対して特定のペイロードを返すなどです。
チームレビューと変更追跡
ApidogでのAPI仕様変更は、すべてのワークスペースメンバーに表示されます。特定のEndPointまたはフィールドにコメントを追加できます。変更履歴は、誰が何をいつ変更したかを追跡します。
デザインファーストのワークフローでは、これは、仕様の変更がコードの変更と同じレビュー文化を経て行われることを意味し、別のツールやプロセスを必要としません。
デザインファースト vs. コードファースト：実際のトレードオフ
デザインファーストは万能ではありません。以下に正直な比較を示します。
デザインファーストの利点：
- フロントエンドとバックエンドが並行して作業できる（大きな開発速度の向上）
- ドキュメントは派生ではなく、情報源であるため正確である
- 統合時の問題が、統合時ではなく設計レビューの早い段階で明らかになる
- API契約が明示的で検証可能である
- APIへの変更はデフォルトでレビュープロセスを経る
デザインファーストの欠点：
- コードを記述する前に仕様を定義するための初期時間
- 仕様ツールには学習曲線がある
- 実装と仕様の同期を保つための規律が必要
- 早期に過度に仕様を決定すると、ドメインを理解する前に決定に縛られてしまう可能性がある
コードファーストの利点：
- 小規模な実験的プロジェクトの場合、初期開発が速い
- 迅速に反復する単独開発者にとってはプロセスが少ない
- 学習すべき仕様ツールがない
コードファーストの欠点：
- ドキュメントは常に二次的な成果物であり、ずれが生じやすい
- フロントエンドは、統合作業を開始する前にバックエンドを待つ必要がある
- 契約が暗黙的であるため、破壊的変更の検出が難しい
- APIのリファクタリングには手動でのドキュメント更新が必要
1人以上のエンジニアがAPIに取り組むチームの場合、デザインファーストは通常、より良い結果をもたらします。仕様ファーストの規律は、フロントエンドとバックエンドの連携が重要な機能で最も効果を発揮します。
デザインファーストワークフローをサポートするツール
Apidog
完全なデザインファーストプラットフォーム：ビジュアルエディタ、インスタントモック、ドキュメント、テスト、チームレビューを1つのツールに。無料プランで全機能が利用可能。強力なモック生成は真の差別化要因です。
Stoplight Studio
スタイル強制のためのSpectralリンティングを備えたクラス最高のOpenAPIエディタ。モックサーバーやテストランナーは内蔵されていません。ガバナンスツールを必要とする組織に最適。小規模チームには高価です。
SwaggerHub
成熟したOpenAPI編集およびコラボレーションプラットフォーム。企業で広く使用されています。モック機能は限定的。テスト機能なし。Swaggerエコシステムにすでに存在する仕様重視の組織に適しています。
Postman（API Builder付き）
PostmanにはOpenAPI仕様を生成するAPIデザインタブがありますが、デザインとコレクションのワークフローは分断されているように感じられます。モックサーバーは、仕様から自動生成されるのではなく、コレクションからの手動設定が必要です。一部のドキュメントツールを求めるコードファーストのチームに適しています。
Insomnia（ドキュメントモード付き）
InsomniaはOpenAPI仕様の編集をサポートし、基本的なモックを提供します。専用のデザインファーストツールよりも洗練されていません。軽量なオプションを求める単独開発者に適しています。
Apidogでデザインファーストワークフローをセットアップする
ステップ1：コレクションではなく仕様から始める新しいプロジェクトを作成し、デザインタブを開きます。リクエストビルダーから始めたい衝動を抑えてください。単一のリクエストを送信する前に、少なくともエンドポイントパス、メソッド、および応答スキーマを定義します。
ステップ2：共有コンポーネントを最初に定義するエンドポイントを追加する前に、エラー応答フォーマット、ページネーションラッパー、共通エンティティフィールドなど、再利用されるスキーマを定義します。これにより、後での不整合を防ぎます。
ステップ3：早めにモックURLを取得するエンドポイントが保存されたらすぐにモックURLをコピーします。フロントエンドエンジニアと共有してください。彼らはすぐにそれに対して開発を開始できます。
ステップ4：コードを記述する前にドキュメントをレビューする生成されたドキュメントをプレビューします。ドキュメント内のフィールドの説明が不明確な場合、コードを読むすべての人にとっても不明確になるでしょう。仕様で修正してください。
ステップ5：実装を開始する前に仕様をロックする設計レビューが完了し、コメントが解決されたら、そのスプリントでは仕様をロックされたものとして扱います。仕様の更新を必要とする実装の変更は、黙って行われるのではなく、レビュープロセスを経るべきです。
ステップ6：CIでスキーマ検証テストを実行するApidogのテストスイートを設定して、CI実行ごとにレスポンススキーマを検証します。これが、実装と仕様を同期させる自動化されたガードレールです。
よくある質問
デザインファーストはREST API専用ですか？いいえ。デザインファーストの原則は、契約を定義できるあらゆるプロトコルに適用されます。GraphQLのスキーマファースト、protobufを使用するgRPC、イベント駆動システムのためのAsyncAPIなどです。ApidogはRESTおよびGraphQLのデザインをサポートしています。gRPCの場合、protoファイルは同じく契約ファーストの目的を果たします。
開発を開始する前にすべてのエンドポイントを定義する必要がありますか？いいえ。機能レベルでデザインファーストを採用できます。コードを記述する前に、構築しようとしている機能の仕様を定義します。コードベースの他の部分がコードファーストであっても構いません。段階的な採用は機能します。
デザインファーストはアジャイルスプリントとどのように連携しますか？スプリントの開始時の設計セッションで、そのスプリントの機能のAPI契約が定義されます。スプリント中、フロントエンドとバックエンドは並行して作業します。仕様レビューはスプリント計画の一部となります。
実装が元の仕様から逸脱する必要がある場合はどうなりますか？そういうこともあります。正しいプロセスは、まず仕様を更新し、ステークホルダー（特にフロントエンド）から合意を得てから、実装を更新することです。これにより、実装ではなく仕様が信頼できる唯一の情報源として維持されます。
ApidogのOpenAPIエクスポートからサーバースタブを生成できますか？はい、できます。ApidogからOpenAPI 3.xとして仕様をエクスポートし、任意の標準コードジェネレーターを使用してサーバースタブを作成できます。openapi-generatorは50以上のサーバー言語とフレームワークをサポートしています。
仕様のバージョン管理はどのように行いますか？Apidogはプロジェクト内で変更履歴を保持します。並行して保守される主要バージョン変更（v1とv2が両方アクティブな場合）には、別々のプロジェクトまたはブランチがうまく機能します。
デザインファーストは、規律に対する少額の先行投資が必要ですが、統合コストの削減という形で大きく報われます。選択するプラットフォームは、その先行投資を可能な限り低く抑えるべきです。仕様書の作成が苦痛であれば、チームはそれをスキップするでしょう。Apidogのビジュアルエディタ、インスタントモック、およびドキュメントプレビューは、デザインファーストを最も美徳のある道ではなく、最も抵抗の少ない道にします。