ApidogのAPIモジュールでは、APIコントラクトという同じものを構築するための2つの方法を提供しています。1つはビジュアルフォームを使用し、もう1つはGitに接続された生のコードエディターを使用します。どちらも有効なOpenAPIを生成します。違いは、チームが日々の作業をどのように行うかにあり、どちらが適しているかは、ツールよりもチームの習慣に左右されます。
このガイドでは、Apidogにおけるデザインファーストとスペックファーストの選択について説明します。各モードがどのようなもので、Gitをどのように扱い、どのチームがどちらを選ぶ傾向があるのかを解説します。APIモジュールの左下にある単一のトグルでモードを切り替えることができるため、選択は永続的なものではありません。しかし、適切なデフォルトを選択することで、無駄な手間を省くことができます。
2つの哲学
各モードに入る前に、考え方について説明します。どちらのアプローチも共通のルールを共有しています。それは、実装を記述する前にAPIコントラクトを定義するということです。コントラクトが真実の情報源であり、コード、テスト、モック、ドキュメントはすべてそこから派生します。
デザインファーストとは、構造化されたインターフェースを通じてコントラクトを形作ることを意味します。フォームやドロップダウンを通じてエンドポイント、パラメーター、スキーマを追加します。このツールは、有効な値しか入力できないため、出力が有効であることを保証します。
スペックファースト（しばしば「コントラクトファースト」とも呼ばれる）とは、OpenAPIをYAMLまたはJSONで直接仕様ファイルとしてコントラクトを記述することを意味します。このスペックが作業対象であり、ソースコードのように編集します。
これらの用語は実際には重複しています。「コントラクトファースト」と「スペックファースト」はほぼ同義であり、多くのチームは「デザインファースト」を、コントラクトがコードに先行するあらゆるアプローチを漠然と指す言葉として使用しています。ここでの有用な区別は具体的です。Apidogでは、一方のモードではフォームが提供され、もう一方のモードではテキストエディターが提供されます。選択する際に重要なのはこの違いです。
これらを、デザインファーストとコードファーストのAPI開発とは区別する価値があります。コードファーストは、実装内のアノテーションからスペックを生成するため、コードが主導します。Apidogのどちらのモードも、コードよりもコントラクトを優先します。ただ、その作成方法が異なるだけです。スペックをバージョン管理された成果物として扱う全体像については、GitネイティブAPIワークフローの概要をご覧ください。
Apidog デザインファーストモード
デザインファーストモードはビジュアルデザイナーです。メソッドの選択、パスの命名、クエリおよびパスパラメーターの追加、ツリーエディターによるリクエストおよびレスポンススキーマの定義、例の添付など、ガイド付きインターフェースを通じてエンドポイントを構築します。Apidogはバックグラウンドで基盤となるOpenAPIをレンダリングします。
このモードはほとんどのチームにとってデフォルトであり、それには十分な理由があります。OpenAPIの構文を覚える必要はありません。スキーマエディターが構造を強制するため、括弧の配置ミスや無効な型を含むスペックをリリースすることはできません。共有のErrorスキーマや共通ヘッダーのような再利用可能なコンポーネントは、数クリックで利用できます。
デザインファーストモードはブランチもサポートしているため、チームはAPI設計の異なるバージョンを並行して作業し、後で調整することができます。レビュー担当者は生テキストではなく構造化された差分を見るため、YAMLに慣れていない人でもコントラクトの変更が読みやすくなります。
トレードオフとして、抽象化を通じて作業することになります。すでにOpenAPIで考えている場合、フォームは頭の中にあるスペックと自分との間に余計なクリックがあるように感じるかもしれません。
Apidog スペックファーストモード
現在ベータ版であるスペックファーストモードは、その逆です。フォームの代わりに、IDEスタイルのコードエディターが提供され、OpenAPIまたはSwaggerのスペックをYAMLまたはJSONで直接記述します。これは、API定義を他のソースファイルと同様にGitで管理したいチーム向けに構築されています。
このエディターは、コードエディターと同様に動作します。OpenAPIおよびSwaggerスキーマに合わせたシンタックスハイライト、インラインバリデーション、自動補完機能が備わっています。入力すると、左側のサイドバーがスペックを自動的に解析し、パスとコンポーネントのアウトラインを表示するため、大きなファイルでもスクロールせずに移動できます。同期インジケーターは、ローカルの編集が接続されたリポジトリと同期しているかどうかを示します。
最大の特徴は、双方向のGit同期です。GitHubまたはGitLabのリポジトリを接続すると（Azure DevOpsは汎用Git接続を介して機能します）、Apidogはスペックファイルを両方向に同期します。Apidogで編集し、アプリから直接コミットしてプッシュします。または、コードエディターでスペックを編集し、そこからプッシュして、変更をApidogにプルバックすることも可能です。スペックファイルが共有された真実であり、両方のインターフェースは常に同期した状態を保ちます。完全な設定については、スペックファーストモードのドキュメントをご覧ください。
このモードでは、APIコントラクトを他のコード成果物と同様に扱います。プルリクエストでのレビュー、それを実装するサービスと並行してバージョン管理、そして行ごとの差分表示が可能です。もしチームがすでにインフラストラクチャや設定をそのように管理している場合、その理由については、コードとしてのAPIスペックに関するより詳細な記事をご覧ください。
比較表
どちらのモードも同じOpenAPIを生成し、モック、テスト、および下流のドキュメント作成をサポートします。両者の違いは、スペックの作成方法とバージョン管理方法にあります。
| デザインファーストモード | スペックファーストモード (ベータ) | |
|---|---|---|
| エディター | ビジュアルフォームとスキーマツリー | IDEスタイルのYAML/JSONコードエディター |
| スペック形式 | OpenAPI (自動生成) | OpenAPI / Swagger (手動で記述) |
| Gitワークフロー | Apidog内でのブランチサポート | GitHub、GitLab、Azure DevOps (Git接続) との双方向同期; アプリからのコミットとプッシュ |
| バリデーション | フォーム入力によって強制 | インライン構文バリデーションと自動補完 |
| ナビゲーション | エンドポイントリストとフォルダー | 左サイドバーの自動解析されたアウトライン |
| 学習曲線 | 低い; OpenAPIの知識不要 | 高い; OpenAPIの知識が必要 |
| 最適な用途 | 複合スキルチーム、迅速なオンボーディング | スペックをコードとして扱うエンジニア |
どちらのモードをどのチームが選ぶべきか
貢献者がすべてOpenAPIの専門家でない場合は、デザインファーストモードを使用してください。プロダクトマネージャー、QA、ジュニアエンジニアは、スペックの構文を学ぶことなく、エンドポイントを追加またはレビューできます。また、新しいAPIをゼロから開始し、フォーマットを気にせずに迅速に構造を構築したい場合には、より速い方法です。
スペックがすでに、またはサービスコードの隣のGitリポジトリに存在すべきである場合は、スペックファーストモードを使用してください。プルリクエストでAPIの変更をレビューしたり、CIでスペックリンティングを実行したり、ツール間で単一の規範的なYAMLファイルを必要とするバックエンドチームは、このモードになじむでしょう。双方向同期により、Apidogは真実の分離されたコピーではなくなり、リポジトリが保持する同じファイルへのウィンドウとなります。
実用的な中間的な道として、多くのチームは速度のためにデザインファーストモードで新しいエンドポイントを設計し、APIが成熟しGitレビューが優先事項となったらスペックファーストモードに移行します。これらのモードは競合する製品ではありません。1つのコントラクトに対する2つの異なる見方です。
モードの切り替え方
切り替えは単一のトグルで行います。ApidogプロジェクトのAPIモジュールを開き、左下隅にあるモードスイッチャーを探してください。それを切り替えるだけで、同じコントラクトが別のモードで表示されます。
切り替える際に留意すべき点がいくつかあります。
- 基盤となるスペックは共有されているため、エンドポイント、スキーマ、例は引き継がれます。APIを再構築するのではなく、編集インターフェースを変更するだけです。
- スペックファーストモードのGit同期を使用するには、まずGitHub、GitLab、またはAzure DevOpsリポジトリを接続してください。接続後、同期インジケーターは編集がコミットされプッシュされたかどうかを示します。
- スペックファーストモードはベータ版であるため、本番コントラクトで信頼する前に、同期動作を確認できるプロジェクトで試してください。
ニーズの変化に応じて行ったり来たりできるため、この選択は恒久的なものではなく、デフォルトとして扱ってください。
よくある質問
スペックファーストはコントラクトファーストと同じですか？
実際には、はい。「スペックファースト」と「コントラクトファースト」はどちらも、実装の前にAPI仕様を作成し、その仕様を真実の情報源として扱うことを意味します。Apidogのスペックファーストモードは、コントラクトが手書きのOpenAPIまたはSwaggerファイルであり、Gitに同期されるコントラクトファーストのワークフローです。
スペックファーストモードはGitLabおよびAzure DevOpsと連携しますか？
はい。スペックファーストモードは、GitHubおよびGitLabとの双方向Git同期を直接サポートしています。Azure DevOpsは汎用Git接続を介して機能するため、Azureでホストされているリポジトリにもスペックファイルを同期できます。
デザインファーストからスペックファーストに切り替えても作業内容は失われませんか？
はい。どちらのモードも同じ基盤となるコントラクトを読み書きするため、APIモジュールの左下にあるトグルを切り替えても、エンドポイント、スキーマ、および例は損なわれません。データを交換するのではなく、エディターを切り替えるだけです。
どちらのモードがあなたのチームに合っているか分かりませんか？APIモジュールを開き、左下のモードトグルを試して、次のエンドポイントを両方の方法で設計してみてください。コントラクトはどちらの方法でも同じです。チームがすでにどのように作業しているかに合ったインターフェースを選択してください。