Akira

Posted on Jun 2 • Originally published at apidog.com

GitネイティブAPIワークフローとは？構築方法

あなたのコードはGitにあります。CIパイプライン、レビュー、リリース履歴もGitにあります。それなら、API仕様書も同じ場所で管理するべきです。

GitネイティブなAPIワークフローでは、OpenAPI定義をコードと同じリポジトリに置きます。仕様書をYAMLまたはJSONファイルとして編集し、コミットし、プルリクエストでレビューします。クラウド上の別データベースに保存したり、エクスポート・インポートを繰り返したりする必要はありません。

💡 Apidogは現在、Spec-Firstモードでこのワークフローをサポートしています。IDEスタイルのエディタでAPIを設計し、生のOpenAPIファイルをGitHubまたはGitLabと双方向で同期できます。このガイドでは、GitネイティブなAPIワークフローの考え方、クラウドにロックされた仕様書が生む摩擦、Spec-Firstモードの設定手順を説明します。

GitネイティブなAPIワークフローとは

GitネイティブなAPIワークフローは、API仕様書をコードとして扱う方法です。OpenAPIファイルをサービスのリポジトリに置き、すべての変更をGitのコミットとして管理します。

この方法では、ソースコードと同じ運用がAPI仕様書にも適用できます。

バージョン履歴

誰が、いつ、どのエンドポイントを変更したかを確認できます。git blameも仕様書に対して使えます。
ブランチとレビュー

仕様書の変更をプルリクエストでレビューできます。レビュー担当者は、マージ前に行単位の差分を確認できます。
単一の真実の源

mainブランチ上のOpenAPIファイルが契約になります。ドキュメント、モック、コード生成、テストはそこから読み取ります。

これはSpec-First APIワークフローの基本です。仕様が先にあり、実装がそれに従います。詳しくはSpec-First API開発のガイドを参照してください。

クラウドにロックされたAPI仕様書の問題点

多くのAPI設計ツールは、仕様書を独自のクラウドデータベースに保存します。UI上ではファイルを編集しているように見えても、実際にはツール内のデータとして管理されています。

この構成では、チーム開発で次のような問題が起きやすくなります。

レビューが分断される

コードの変更はGitHubやGitLabでレビューします。一方、仕様書の変更は別ツールのコメントや履歴でレビューされます。

結果として、レビュー担当者はコンテキストを切り替える必要があり、コードとAPI契約の承認タイミングがずれます。

差分が見えにくい

仕様書がクラウドデータベース内にある場合、プルリクエスト上で明確な行単位の差分を確認できません。

「デザインのv3」を承認しても、実際にどのパス、スキーマ、レスポンスが変わったのかが分かりにくくなります。

エクスポート運用が増える

CIで仕様書を使うには、クラウドツールからOpenAPIファイルをエクスポートし、それをリポジトリにコミットする必要があります。

この場合、クラウド上の仕様書とGit上の仕様書という2つの真実の源が生まれます。同期漏れや競合の原因になります。

自動化しにくい

リンター、契約テスト、コードジェネレーターは、通常ディスク上のファイルを入力として使います。クラウドにロックされた仕様書では、CI実行前に取得ステップが必要になります。

API仕様書をコードとして扱えば、これらの問題を減らせます。ファイルが仕様書であり、Gitが履歴になります。この考え方については、API仕様書をコードとして扱うで詳しく説明しています。

Apidog Spec-Firstモードの仕組み

Spec-Firstモードは、コミット、ブランチ、プルリクエストを中心に作業しているチーム向けのモードです。

API仕様書を生のYAMLまたはJSONファイルとして設計し、ApidogがそれらのファイルをGitリポジトリと双方向で同期します。

IDEスタイルのOpenAPIエディタ

Spec-Firstモードでは、フォームではなくコードエディタでOpenAPIファイルを編集します。

利用できる主な機能は次のとおりです。

YAML / JSONのシンタックスハイライト
OpenAPI / Swaggerスキーマに対する検証
OpenAPIキーワード、型、参照のオートコンプリート

ファイルの中身を直接管理できるため、隠れたフィールドやUI専用メタデータに依存しません。

生のYAML / JSONファイル

仕様書は実際のファイルとしてリポジトリに保存されます。

例：

openapi: 3.1.0
info:
  title: Orders API
  version: 1.2.0

paths:
  /orders/{orderId}:
    get:
      summary: Get an order by ID
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Order found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Order not found

components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, shipped, delivered]

このファイルがそのままGitにコミットされます。編集した内容とレビューされる内容が一致します。

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

ApidogはOpenAPIファイルを解析し、左サイドバーにアウトラインを表示します。

パス、操作、スキーマがクリック可能なツリーとして表示されるため、長い仕様書でも目的のエンドポイントにすばやく移動できます。

これにより、生ファイルの正確さを保ちながら、設計ツールとしての読みやすさも得られます。

双方向Git同期

Spec-FirstモードはGitプロバイダーに接続し、変更を双方向で同期します。

サポートされる接続は次のとおりです。

GitHub
GitLab
Azure DevOps（Git接続経由）

チームメイトがリモートにプッシュした変更を取り込み、Apidogエディタで編集し、同じブランチにコミットしてプッシュできます。

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

Git操作のためにApidogを離れる必要はありません。

Apidog上で次の操作を行えます。

変更ファイルを確認する
コミットメッセージを書く
コミットする
リモートブランチへプッシュする
同期ステータスを確認する

プッシュが成功すると、「たった今同期されました」のようなステータスが表示されます。プッシュ前に変更を取り消したい場合は、未プッシュの編集を破棄して最後に同期された状態へ戻せます。

GitHubとの同期手順については、OpenAPI仕様書をGitHubに同期するを参照してください。

セットアップ手順

ここでは、空のリポジトリまたは既存リポジトリから、Git同期されたOpenAPI仕様書を扱う流れを説明します。完全なリファレンスはSpec-Firstモードのドキュメントにあります。

1. リポジトリからプロジェクトを作成する

Apidogで新しいSpec-Firstプロジェクトを作成し、Gitプロバイダーを接続します。

選択する項目は次のとおりです。

API仕様書を保持するリポジトリ
追跡するブランチ（通常はmain）
使用するOpenAPIファイル

Apidogは既存の仕様書ファイルをエディタに読み込みます。

2. OpenAPI仕様書を編集する

エディタでOpenAPIファイルを開き、必要な変更を加えます。

例：

新しいエンドポイントを追加する
リクエストパラメータを変更する
レスポンススキーマを修正する
エラー応答を追加する

入力中は、シンタックスハイライト、検証、オートコンプリートが補助します。ファイルを変更すると、左サイドバーのアウトラインも更新されます。

3. 変更ファイルを確認する

Apidogは、前回の同期以降に変更されたファイルを表示します。

確認できる状態は次のとおりです。

変更されたファイル
追加されたファイル
削除されたファイル

コミットに含まれる内容を事前に把握できます。

4. コミットメッセージを書く

変更内容が分かるコミットメッセージを書きます。

悪い例：

仕様書を更新

良い例：

getOrderに404レスポンスを追加

コードと同じように、仕様書の変更も後から追跡しやすいメッセージにします。

5. プッシュする

コミットを追跡対象のブランチにプッシュします。

これで、チームメイトやCIパイプラインが新しいOpenAPI仕様書を参照できます。

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

プッシュ後、同期ステータスを確認します。

「たった今同期されました」と表示されれば、Apidog上の編集内容とリモートブランチの内容が一致しています。

基本のループは次のとおりです。

pull → edit → commit → push → verify

エクスポート手順は不要です。第二の真実の源も作りません。

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

Apidogには2つの作業方法があります。違いは、仕様書の保存場所と編集方法です。

項目	Spec-Firstモード（ベータ版）	Design-Firstモード
仕様書の保存場所	Git内の生のYAML / JSONファイル	Apidogクラウドプロジェクト
主要エディタ	IDEスタイルのコードエディタ	ビジュアルなフォームベースUI
バージョン管理	ネイティブGit（コミット、ブランチ、差分）	Apidogの履歴とブランチ
双方向Git同期	あり（GitHub、GitLab、Azure DevOps）	エクスポート / インポート経由
最適な用途	Git中心で作業するチーム	ビジュアルなワークフローを好むチーム

どちらかが常に優れているわけではありません。

レビューとリリースがすでにGitで管理されているなら、Spec-Firstモードが自然です。チームが生のOpenAPIにあまり触れず、視覚的に設計する場合は、Design-Firstモードの方が合う場合があります。

Spec-Firstモードを使うべきケース

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

API仕様書をプルリクエストとコードレビューに含めたい
API契約に対してgit blameとコミット履歴を使いたい
CIで仕様書のリンティング、契約テスト、コード生成を実行したい
複数のエンジニアがOpenAPIファイルを編集する
マージ可能で明確な差分が必要
クラウドツールからのエクスポート運用を避けたい

一方で、チームが生のOpenAPIを編集せず、非エンジニアがフォームベースのUIで仕様書を管理する場合は、ビジュアルでクラウドファーストな運用を継続する方が適している場合があります。

よくある質問

GitネイティブAPIワークフローとは何ですか？

GitネイティブAPIワークフローは、OpenAPI仕様書をGitリポジトリ内のファイルとして保存し、コミット、ブランチ、プルリクエストで変更を管理する方法です。

仕様書はアプリケーションコードと同じレビュー、履歴管理、リリースプロセスに従います。

Apidog Spec-FirstモードはGitHubとGitLabをサポートしていますか？

はい。Spec-FirstモードはGitHubとGitLabとの双方向同期をサポートしています。Azure DevOpsはGit接続を介してサポートされています。

リポジトリとブランチを選択すると、Apidogが編集内容とリモートを同期します。

OpenAPIファイルを生のYAMLまたはJSONとして編集できますか？

はい。Spec-Firstモードでは、生のYAMLおよびJSONをIDEスタイルのエディタで編集できます。

エディタには次の機能があります。

シンタックスハイライト
スキーマ検証
OpenAPI / Swaggerのオートコンプリート
自動解析されるアウトライン

大規模な仕様書でも、パスやスキーマへすばやく移動できます。

Spec-FirstモードとDesign-Firstモードの違いは何ですか？

Spec-Firstモードは、仕様書をGit内のファイルとして保持し、コードエディタで編集します。Gitとの双方向同期により、コミット、ブランチ、差分、レビューをそのまま利用できます。

Design-Firstモードは、仕様書をApidogクラウドプロジェクトに保持し、ビジュアルなフォームベースUIで編集します。

ワークフローがすでにGit中心なら、Spec-Firstモードを選ぶのが自然です。

結論

GitネイティブAPIワークフローは、コードとAPI契約の分離をなくします。仕様書はファイルになり、ファイルはコミットになり、そのコミットは既存のレビュープロセスを通ります。

Apidog Spec-Firstモードでは、IDEスタイルのエディタ、ナビゲーション可能なアウトライン、双方向Git同期を使ってこの運用を実現できます。

生のYAMLまたはJSONを編集し、明確なコミットメッセージを書き、プッシュするだけです。

Spec-Firstモードを試して、API仕様書をGitに戻しましょう。

DEV Community