アピドッグのスペックファーストモードとは？

Apidog Spec-Firstモードは、OpenAPI仕様をソースコードとして扱うチーム向けのベータ版ワークスペースです。IDEスタイルのエディタでopenapi.yamlまたはopenapi.jsonを直接編集し、接続したGitリポジトリと双方向に同期できます。フォームベースのUIを介さず、仕様ファイルそのものを編集・検証・コミット・プッシュするワークフローです。

今すぐApidogを試す

このガイドでは、Spec-Firstモードの機能、セットアップ手順、日々の使い方、向いているチーム、ベータ版での注意点を実装目線で整理します。Gitを中心にAPI契約を管理する考え方については、GitネイティブAPIワークフローも参考にしてください。

Apidog Spec-Firstモードとは？

Spec-Firstモードは、APIデザインを生のOpenAPIドキュメントとして扱うApidogのベータ版編集モードです。

基本フローは次の通りです。

1. Gitリポジトリ内のOpenAPI仕様ファイルを開く
2. YAMLまたはJSONを直接編集する
3. OpenAPI仕様として検証する
4. 変更内容を確認する
5. コミットしてGitにプッシュする
6. チームメイトの変更をプルして同期する

このモードは、すでにGitベースで開発しているバックエンドエンジニア、プラットフォームチーム、APIファーストな開発組織に向いています。仕様ファイルを唯一の信頼できる情報源として扱い、履歴管理、レビュー、ブランチ運用をGitに任せられます。

多くのAPIツールは、GUIフォームの裏側に仕様を隠します。一方、Spec-Firstモードではファイルそのものを編集対象にします。

Spec-Firstモード vs Design-Firstモード

Apidogには主に2つの編集モードがあります。

• Design-Firstモード: フォームやUIパネルでAPIを設計するモード
• Spec-Firstモード: YAML/JSONのOpenAPI仕様を直接編集するモード

詳しい比較は、Spec-First vs Design-First比較を参照してください。

側面	Design-Firstモード	Spec-Firstモード（ベータ）
主要エディタ	ビジュアルフォームとUIパネル	生のYAML/JSONコードエディタ
信頼できる情報源	Apidogプロジェクトデータベース	Gitリポジトリ内の仕様ファイル
Git同期	エクスポート/インポートベース	ネイティブな双方向同期
向いているチーム	ビジュアル設計を好むチーム、混合チーム	Gitネイティブなエンジニアリングチーム
学習曲線	緩やかでガイド付き	OpenAPIに慣れていれば扱いやすい

どちらが常に優れているというものではありません。チームがどのようにAPI契約を作成・レビュー・運用しているかで選択します。

主要機能

Spec-Firstモードは、単なるテキストエディタではありません。OpenAPI向けのコードエディタ、アウトライン、Git同期、変更追跡、チーム権限管理を組み合わせたワークスペースです。

IDEスタイルのOpenAPIエディタ

Spec-Firstモードの中心は、OpenAPIドキュメント用のコードエディタです。openapi.yamlまたはopenapi.jsonを直接編集できます。

エディタでは次の機能を利用できます。

• YAML/JSONのシンタックスハイライト
• OpenAPI/Swagger向けのスキーマ検証
• フィールド名や構造のオートコンプリート
• 不正なレスポンス定義や必須フィールド欠落の検出

たとえば、次のようなOpenAPIパス定義を直接編集します。

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

OpenAPIの構造を手で書く場合、additionalPropertiesやparameters、requestBodyなどの正確なフィールド名を思い出す必要があります。オートコンプリートがあることで、仕様の記述ミスを減らせます。

自動解析されるナビゲーション可能なアウトライン

実際のOpenAPIファイルはすぐに数千行規模になります。Spec-Firstモードでは、左サイドバーに仕様ファイルから自動生成されたアウトラインが表示されます。

アウトラインでは、次のような単位で移動できます。

• パス
• HTTPメソッドごとの操作
• スキーマ
• コンポーネント
• リクエスト/レスポンス定義

これにより、1847行目を探すのではなく、POST /ordersやcomponents.schemas.Userといった意味単位で移動できます。編集に応じてアウトラインも更新されるため、大きな仕様ファイルでも作業しやすくなります。

双方向Git同期

Spec-Firstモードの中核は、Gitリポジトリとの双方向同期です。

サポートされる接続方法は次の通りです。

プロバイダー	接続方法
GitHub	直接統合
GitLab	直接統合
Azure DevOps	汎用Git接続経由

接続後は、次の操作ができます。

• リポジトリから最新の仕様をプルする
• Apidog上で仕様を編集する
• 変更をコミットする
• 接続されたブランチにプッシュする

GitHubへの同期手順を詳しく確認したい場合は、OpenAPI仕様をGitHubに同期するガイドを参照してください。

コミット、プッシュ、同期ステータス

Spec-Firstモードでは、単にファイルを保存するだけではありません。Gitの基本モデルに従って、変更をコミットし、リポジトリへプッシュします。

実際の作業では、次のような流れになります。

1. YAML/JSONを編集する
2. 変更内容を確認する
3. コミットメッセージを書く
4. コミットする
5. リモートブランチにプッシュする
6. 同期ステータスを確認する

同期ステータスインジケーターにより、現在の仕様がリポジトリと一致しているか、未プッシュの変更があるかを確認できます。たとえば「Synced just now」と表示されれば、ローカルの仕様と接続先リポジトリが同期済みです。

ファイル変更の追跡

コミット前に、Spec-Firstモードは変更されたファイルを表示します。変更は次のように分類されます。

• 修正
• 追加
• 削除

これはgit statusや差分確認に近い役割を持ちます。誤って編集した内容があれば、リポジトリにプッシュする前に破棄できます。

API仕様はチーム全体に影響する契約です。コミット前に変更範囲を確認できることで、不要な差分や実験的な編集を共有履歴に入れずに済みます。

ブランチ・リポジトリ単位のプロジェクト管理

Spec-Firstプロジェクトは、特定のリポジトリとブランチに紐付けて作成します。通常はmainなどのブランチを選択します。

このスコープ設定により、Apidog上のプロジェクトとGit上の実体が一致します。

• 仕様ファイル
• Git履歴
• ブランチ
• チームのアクセス権限

セットアップ時には、誰がプロジェクトにアクセスでき、どの操作ができるかも設定できます。Git側の運用と合わせて、API契約を管理するチームを制御できます。

Spec-Firstモードのセットアップ手順

公式ドキュメントは、docs.apidog.com/spec-first-mode-beta-2058268m0にあります。

実際のセットアップは次の流れです。

1. APIモジュールでモードを切り替える

ApidogのAPIモジュールを開きます。モジュール左下にあるモード切り替えから、Design-FirstモードからSpec-Firstモードへ切り替えます。

2. Gitプロバイダーを接続する

利用するGitプロバイダーを選択します。

• GitHub: 直接認証
• GitLab: 直接認証
• Azure DevOps: 汎用Git接続とGitクレデンシャルを使用

3. リポジトリとブランチを選択する

OpenAPI仕様ファイルを含むリポジトリを選びます。次に、対象ブランチを選択します。多くの場合はmainを使います。

Apidogは、このリポジトリとブランチを基準にプロジェクトを作成します。

4. チーム権限を設定する

プロジェクトにアクセスできるメンバーと権限を設定します。API契約を編集できる人を明確にしておくと、意図しない仕様変更を防ぎやすくなります。

5. OpenAPI仕様を編集する

IDEスタイルのエディタで、openapi.yamlまたはopenapi.jsonを開きます。

作業時は次の機能を使います。

• アウトラインで対象エンドポイントへ移動
• オートコンプリートでフィールド名を補完
• スキーマ検証でOpenAPIの不整合を検出

6. 変更内容を確認してコミットする

ファイル変更の追跡画面で差分を確認します。問題なければ、明確なコミットメッセージを書いてコミットします。

例:

Add POST /invoices endpoint

7. リポジトリにプッシュする

コミットした変更を接続されたブランチにプッシュします。

8. 同期ステータスを確認する

最後に同期ステータスインジケーターを確認します。「Synced just now」のような状態であれば、仕様とリポジトリが一致しています。

この一連のループは次のように覚えると簡単です。

切り替え → 接続 → 作成 → 編集 → 確認 → コミット → プッシュ → 同期確認

日々のワークフロー例

セットアップ後は、通常のGitワークフローに近い形でAPI仕様を更新できます。

例: 新しいエンドポイントを追加する

1日の作業開始時に、接続されたブランチから最新の変更をプルします。チームメイトが前日にマージしたAPI仕様の変更を取り込みます。

次に、アウトラインから対象のパスやスキーマに移動します。たとえば、請求書APIを追加する場合、次のようなスキーマを編集します。

components:
  schemas:
    Invoice:
      type: object
      required: [id, amount, currency]
      properties:
        id:
          type: string
          format: uuid
        amount:
          type: integer
          description: Amount in the smallest currency unit
        currency:
          type: string
          example: USD
        status:
          type: string
          enum: [draft, sent, paid]

続いて、POST /invoicesのパスを追加します。

paths:
  /invoices:
    post:
      summary: Create an invoice
      operationId: createInvoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Invoice'
      responses:
        '201':
          description: Invoice created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'

編集後は、検証エラーがないか確認します。問題なければ変更内容を確認し、次のようなコミットメッセージでコミットします。

Add POST /invoices endpoint

その後、接続されたブランチにプッシュします。同期ステータスが更新されれば、チームメイトは通常のGitレビューやプルリクエストの流れで仕様変更を確認できます。

Spec-Firstモードが向いているチーム

Spec-Firstモードは、特に次のようなチームに向いています。

• OpenAPI仕様をGitで管理している
• API契約をプルリクエストでレビューしている
• サービスコードの近くに仕様ファイルを置きたい
• バックエンドエンジニアがYAML/JSONを直接編集する
• API仕様をプロダクトの中心的な成果物として扱っている
• CI/CDやコード生成などでOpenAPIファイルを利用している

一方で、次のようなチームではDesign-Firstモードの方が適している場合があります。

• 非エンジニアもAPI設計に参加する
• YAMLを書くよりフォーム入力を好む
• ガイド付きのビジュアルエディタが必要
• API設計をまずUI上で整理したい

チームにとってどちらが適しているかは、比較記事で詳しく確認できます。

制限事項とベータ版の注意点

Spec-Firstモードはベータ版です。そのため、本番ワークフローに組み込む前に、いくつかの点を確認しておく必要があります。

機能や動作が変わる可能性がある

ベータ版のため、フィードバックに基づいて機能や挙動が変更される可能性があります。重要なAPI仕様を扱う前に、小さなリポジトリや検証用プロジェクトで試すのがおすすめです。

Gitプロバイダーごとに接続方法が異なる

GitHubとGitLabは直接統合に対応しています。Azure DevOpsは専用統合ではなく、汎用Git接続を使います。

特定のGitプロバイダーや社内Git運用に依存している場合は、チームの認証方式や権限管理に合うかを事前に確認してください。

通常のGit運用ルールが重要

Spec-Firstモードでは、仕様ファイルが実際のGitリポジトリと同期します。そのため、次のような基本的なGit運用が重要です。

• コミット前に差分を確認する
• 不要な変更は破棄する
• 明確なコミットメッセージを書く
• 意図したブランチにプッシュする
• 重要なブランチではレビューを通す

変更追跡や同期インジケーターはミスを減らす助けになりますが、クリーンな履歴を維持する責任はチーム側にもあります。

FAQ

Spec-Firstモードは無料ですか？

Spec-FirstモードはApidogのベータ機能です。利用可否はApidogのプランやベータ機能の提供状況に依存します。現在のアカウントで使えるかどうかは、APIモジュールでSpec-Firstモードを有効にして確認してください。

どのGitプロバイダーがサポートされていますか？

GitHubとGitLabは直接統合でサポートされています。Azure DevOpsは汎用Git接続を介して利用できます。他のGitホストについても、標準のGit接続に対応していれば利用できる可能性があります。

Design-Firstモードに戻せますか？

はい。APIモジュール左下のモード切り替えから、Spec-FirstモードとDesign-Firstモードを切り替えられます。プロジェクトやチームの作業内容に応じて適したモードを選択できます。

どのファイル形式を編集できますか？

OpenAPIドキュメントをYAMLまたはJSONとして編集できます。エディタはOpenAPIとSwagger向けのシンタックスハイライト、スキーマ検証、オートコンプリートを提供します。

未プッシュの編集はどうなりますか？

未プッシュの編集は、プッシュするまでローカル側に残ります。Spec-Firstモードは変更を修正、追加、削除として追跡し、同期インジケーターで未プッシュ状態を表示します。不要な変更は、リポジトリに反映する前に破棄できます。

結論

Apidog Spec-Firstモードは、OpenAPIエディタとGitワークフローを統合するベータ版モードです。YAMLまたはJSONで仕様を直接編集し、アウトラインで移動し、入力中に検証し、GitHub、GitLab、Azure DevOpsと同期できます。

仕様をソースコードとして扱い、API契約をGitでレビュー・管理したいチームに向いています。まずは小さなリポジトリで、編集、コミット、プッシュ、同期確認のサイクルを試してください。準備ができたら、ドキュメントでSpec-Firstモードを試して、実際のAPI仕様管理に組み込めます。