DEV Community

Cover image for Apidog仕様優先かデザイン優先か？最適なモードの選び方
Akira
Akira

Posted on • Originally published at apidog.com

Apidog仕様優先かデザイン優先か？最適なモードの選び方

ApidogのAPIモジュールでは、APIコントラクトを作成する方法として、ビジュアルフォームを使う「デザインファーストモード」と、Gitに接続されたコードエディターでOpenAPI/Swaggerを直接編集する「スペックファーストモード」を選べます。どちらも有効なOpenAPIを生成します。違いは、API仕様をフォームで組み立てるか、YAML/JSONファイルとして管理するかです。

Apidogを今すぐ試す

この記事では、Apidogでどちらのモードを選ぶべきかを実装手順ベースで整理します。APIモジュール左下のトグルで切り替えられるため、選択は固定ではありません。ただし、チームの作業スタイルに合うデフォルトを選ぶと、レビュー、Git管理、オンボーディングが楽になります。

2つの考え方

どちらのモードでも重要なのは、実装前にAPIコントラクトを定義することです。

APIコントラクトを先に決めると、次の成果物を同じ仕様から派生できます。

  • モック
  • テスト
  • ドキュメント
  • クライアント/サーバー実装
  • レビュー対象のAPI変更

Apidogでは、同じ「コントラクトファースト」の考え方を2つの編集方法で扱えます。

デザインファースト

デザインファーストでは、フォームやスキーマツリーを使ってAPIを定義します。

たとえば、次のような作業を画面上で行います。

  1. HTTPメソッドを選ぶ
  2. パスを入力する
  3. パスパラメーターやクエリパラメーターを追加する
  4. リクエストボディのスキーマを定義する
  5. レスポンススキーマとサンプルを登録する

OpenAPIのYAML構文を直接書く必要はありません。Apidogが裏側でOpenAPIを生成します。

スペックファースト

スペックファーストでは、OpenAPIまたはSwaggerの仕様ファイルをYAML/JSONで直接編集します。

たとえば、次のようなOpenAPI定義をコードとして扱います。

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
Enter fullscreen mode Exit fullscreen mode

スペックをGitリポジトリで管理し、プルリクエストやCIの対象にしたいチームに向いています。

なお、ここでの「スペックファースト」と「コントラクトファースト」はほぼ同じ意味です。実装より先に仕様を定義し、その仕様を真実の情報源として扱います。

一方で、コード内のアノテーションから仕様を生成する「コードファースト」とは異なります。Apidogの両モードは、どちらもコードよりコントラクトを優先します。スペックをバージョン管理された成果物として扱う全体像は、GitネイティブAPIワークフローも参考になります。

Apidog デザインファーストモードの使いどころ

デザインファーストモードは、OpenAPIに詳しくないメンバーもAPI設計に参加しやすい編集モードです。

実装の流れはシンプルです。

  1. ApidogでAPIモジュールを開く
  2. 新しいエンドポイントを作成する
  3. メソッドとパスを設定する
  4. パラメーターを追加する
  5. リクエスト/レスポンススキーマをツリーエディターで定義する
  6. サンプルレスポンスを追加する
  7. モック、テスト、ドキュメントに展開する

このモードの利点は、構文エラーを起こしにくいことです。フォーム入力によって構造が制約されるため、YAMLのインデントミスや型指定ミスを減らせます。

たとえば、共有の Error スキーマや共通ヘッダーをコンポーネントとして作成し、複数のエンドポイントで再利用できます。

{
  "code": "USER_NOT_FOUND",
  "message": "User was not found"
}
Enter fullscreen mode Exit fullscreen mode

デザインファーストモードは、次のようなチームに向いています。

  • OpenAPIに詳しくないメンバーもAPI設計に参加する
  • PM、QA、フロントエンド、バックエンドが同じ画面でレビューする
  • 新規APIを素早く設計したい
  • スキーマの構造を視覚的に確認したい
  • YAML/JSONの手書きを避けたい

また、Apidog内でブランチを使えるため、複数のAPI案を並行して作成し、後からレビューできます。レビュー担当者は生のYAMLではなく構造化された差分を確認できます。

注意点は、OpenAPIをすでに日常的に書いているエンジニアにとっては、フォーム操作が少し遠回りに感じられる場合があることです。

Apidog スペックファーストモードの使いどころ

スペックファーストモードは、現在ベータ版の機能です。フォームではなく、IDEスタイルのコードエディターでOpenAPI/Swagger仕様を直接編集します。

基本的な作業フローは次のとおりです。

  1. GitHub、GitLab、またはAzure DevOpsのGitリポジトリを接続する
  2. OpenAPI/Swaggerのスペックファイルを指定する
  3. Apidog上でYAML/JSONを編集する
  4. インラインバリデーションで構文を確認する
  5. Apidogからコミットしてプッシュする
  6. または、ローカルエディターで編集してGitからApidogへ同期する

エディターには、OpenAPI/Swagger向けの機能があります。

  • シンタックスハイライト
  • インラインバリデーション
  • 自動補完
  • パスとコンポーネントのアウトライン表示
  • Git同期状態の表示

たとえば、API仕様をサービスコードの隣に置き、次のように管理できます。

my-service/
  src/
  tests/
  openapi/
    api.yaml
Enter fullscreen mode Exit fullscreen mode

この場合、API変更を通常のコード変更と同じように扱えます。

git checkout -b feature/add-user-api
# api.yaml を編集
git add openapi/api.yaml
git commit -m "Add user API contract"
git push origin feature/add-user-api
Enter fullscreen mode Exit fullscreen mode

その後、プルリクエストでAPIコントラクトをレビューできます。

スペックファーストモードの大きな特徴は、双方向Git同期です。GitHubまたはGitLabのリポジトリを接続すると、ApidogとGitリポジトリのスペックファイルを同期できます。Azure DevOpsは汎用Git接続を介して利用できます。

つまり、Apidogは独立した仕様コピーではなく、Gitで管理されている同じスペックファイルを見るインターフェースになります。設定手順は、スペックファーストモードのドキュメントを参照してください。

APIスペックをコード成果物として扱う考え方については、コードとしてのAPIスペックでも詳しく解説されています。

比較表

どちらのモードもOpenAPIを生成し、モック、テスト、ドキュメント作成に使えます。違いは、編集方法とGit管理の仕方です。

デザインファーストモード スペックファーストモード（ベータ）
エディター ビジュアルフォームとスキーマツリー YAML/JSONコードエディター
スペック形式 OpenAPIを自動生成 OpenAPI / Swaggerを直接記述
Gitワークフロー Apidog内のブランチを使用 GitHub、GitLab、Azure DevOps（Git接続）と双方向同期
バリデーション フォーム入力で制約 インライン構文バリデーションと自動補完
ナビゲーション エンドポイントリストとフォルダー 自動解析されたアウトライン
学習コスト 低い 高い
向いているチーム 複数職種でAPI設計するチーム APIスペックをGitで管理するエンジニア中心のチーム

どちらを選ぶべきか

判断基準はシンプルです。

デザインファーストモードを選ぶケース

次の条件に当てはまるなら、デザインファーストモードから始めるのが実用的です。

  • OpenAPIに詳しくないメンバーがいる
  • PM、QA、フロントエンドも仕様レビューに参加する
  • 新規APIを素早く設計したい
  • YAML/JSONの手書きミスを避けたい
  • 仕様作成よりも画面上での整理を優先したい

特に、新しいAPIをゼロから作る場合は、フォームでエンドポイントやスキーマを組み立てる方が速いことがあります。

スペックファーストモードを選ぶケース

次の条件に当てはまるなら、スペックファーストモードが適しています。

  • APIスペックをGitで管理したい
  • 仕様変更をプルリクエストでレビューしたい
  • CIでOpenAPIのリンティングを実行したい
  • サービスコードと同じリポジトリにAPI仕様を置きたい
  • チームがすでにYAML/JSONでOpenAPIを書いている

たとえば、CIでスペック検証を行うチームでは、次のようなワークフローに組み込みやすくなります。

# 例: OpenAPIスペックの検証をCIで実行
npx @redocly/cli lint openapi/api.yaml
Enter fullscreen mode Exit fullscreen mode

スペックファーストモードでは、Apidogで編集した内容もGit上のファイルと同期できるため、仕様の真実が分散しにくくなります。

実用的な移行パターン

多くのチームでは、最初から一方に固定する必要はありません。

実用的には、次の流れが使いやすいです。

  1. 新規APIはデザインファーストモードで素早く設計する
  2. エンドポイント、スキーマ、レスポンス例を固める
  3. チームレビューを通す
  4. APIが成熟したらスペックファーストモードに切り替える
  5. Gitリポジトリに同期し、PRベースの運用に移行する

このように、デザインファーストは設計速度を重視する段階、スペックファーストはGitレビューとCIを重視する段階で使いやすいです。

2つのモードは競合するものではなく、同じAPIコントラクトに対する異なる編集インターフェースです。

モードの切り替え方

Apidogでモードを切り替える手順は次のとおりです。

  1. Apidogプロジェクトを開く
  2. APIモジュールに移動する
  3. 左下のモードスイッチャーを探す
  4. デザインファーストまたはスペックファーストを選択する

切り替え時に注意する点は次のとおりです。

  • 同じ基盤スペックを読み書きするため、エンドポイント、スキーマ、例は引き継がれます
  • APIを作り直す必要はありません
  • 変更されるのは編集インターフェースです
  • スペックファーストモードでGit同期を使う場合は、先にGitリポジトリを接続します
  • スペックファーストモードはベータ版のため、本番コントラクトに適用する前に検証用プロジェクトで同期動作を確認してください

選択は恒久的なものではありません。チームの作業スタイルに合わせて、デフォルトの編集方法として選ぶのがよいでしょう。

よくある質問

スペックファーストはコントラクトファーストと同じですか？

実務上はほぼ同じです。

どちらも、実装前にAPI仕様を定義し、その仕様を真実の情報源として扱う考え方です。Apidogのスペックファーストモードでは、そのコントラクトをOpenAPIまたはSwaggerのYAML/JSONファイルとして直接編集し、Gitと同期します。

スペックファーストモードはGitLabやAzure DevOpsと連携できますか？

はい。

スペックファーストモードは、GitHubとGitLabとの双方向Git同期をサポートしています。Azure DevOpsは汎用Git接続を介して利用できます。

デザインファーストからスペックファーストに切り替えると作業内容は失われますか？

いいえ。

どちらのモードも同じ基盤コントラクトを読み書きします。APIモジュール左下のトグルで切り替えても、エンドポイント、スキーマ、例は引き継がれます。

変更されるのはデータではなく、編集方法です。

まとめ

ApidogでAPIコントラクトを作る場合、選択肢は次の2つです。

  • デザインファーストモード: フォームで素早くAPIを設計したいチーム向け
  • スペックファーストモード: OpenAPI/SwaggerをGitで管理したいチーム向け

どちらを選んでも、基盤となるコントラクトは同じです。

迷った場合は、まずデザインファーストモードで次のエンドポイントを作成し、その後スペックファーストモードに切り替えてYAML/JSONとして確認してみてください。チームが普段使っているレビュー方法やGit運用に合う方をデフォルトにするのが最も実用的です。

Top comments (0)