DEV Community

Cover image for OpenAPI定義をGitHubに同期する2つの方法
Akira
Akira

Posted on • Originally published at apidog.com

OpenAPI定義をGitHubに同期する2つの方法

GitリポジトリにOpenAPIドキュメントがあるのに、APIクライアント側でも別途編集していると、YAMLのコピー＆ペースト、再インポート、差分確認、フィールド欠落の確認が発生します。仕様とリポジトリを手動で同期し続ける運用は、特にリリース前やレビュー中にミスを生みやすくなります。

今すぐApidogを試す

このガイドでは、ApidogのSpec-Firstモードを使って、OpenAPI仕様をGitHubと双方向同期する手順を説明します。リポジトリ内のOpenAPIファイルをApidogで直接開き、YAMLを編集し、変更をGitコミットとしてGitHubへプッシュします。同じ流れはGitLabでも利用できます。

双方向同期とは

双方向同期では、OpenAPI仕様の変更がGitとApidogの間で行き来します。手動エクスポートや再インポートは不要です。

  • Apidog → Git: ApidogでOpenAPIドキュメントを編集し、コミットすると、選択したブランチへ通常のGitコミットとしてプッシュされます。
  • Git → Apidog: チームメイトや自分がIDEから同じブランチへ変更をプッシュすると、Apidogはその変更を取り込み、エディター上の内容をリポジトリの状態に合わせます。

この運用では、リポジトリが唯一の真実の源になります。Apidogは、そのGit管理されたOpenAPI仕様を編集するためのエディターとして機能します。これは、仕様をツール内に閉じ込めず、コードと同じようにレビュー、履歴管理、差分確認を行うためのGitネイティブAPIワークフローです。

前提条件

作業を始める前に、以下を用意してください。

  • Apidogにサインイン済みであること（デスクトップアプリまたはWeb）。
  • OpenAPIドキュメントを含むGitHubまたはGitLabリポジトリがあること。
  • 同期対象ブランチへの書き込み権限があること。
  • Spec-Firstモード（ベータ版）が有効であること。
  • Azure DevOpsを使う場合は、Git接続経由で利用できること。

読み取り専用アクセスでは、リポジトリからの取得はできますが、Apidogからのコミットやプッシュはできません。

ステップ1: Gitプロバイダーを接続する

まず、ApidogがGitHubまたはGitLabへアクセスできるように認証します。

  1. Apidogを開きます。
  2. Spec-Firstモードで新しいプロジェクトを作成します。
  3. ソース選択画面で、GitHubまたはGitLabを選択します。
  4. 「認証」をクリックします。
  5. ブラウザで表示されるOAuth画面で、Apidogにリポジトリへのアクセスを許可します。

GitHubでは、アカウント全体ではなく、特定のリポジトリにアクセス範囲を限定できます。

認証が完了すると、Apidogに戻ります。プロバイダー接続は一度設定すれば、以後のプロジェクトでも再利用できます。

Azure DevOpsをGit接続経由で使う場合を含めた詳細は、Spec-Firstモードのドキュメントを参照してください。

ステップ2: リポジトリとブランチからプロジェクトを作成する

次に、Apidogで編集するOpenAPIファイルを指定します。

  1. 接続済みのGitプロバイダーを選択します。
  2. OpenAPIファイルを含むリポジトリを選択します。
  3. 同期するブランチを選択します。通常はmainですが、保護ブランチの場合は作業用ブランチを選びます。
  4. OpenAPIドキュメントのパスを指定または確認します。
    • 例: openapi.yaml
    • 例: docs/openapi.yaml
  5. プロジェクトを作成します。

Apidogは指定したブランチから仕様を読み込みます。OpenAPIドキュメントが解析され、左側のサイドバーにエンドポイントやスキーマが表示されます。

この時点で、Apidog上で見ている内容は、リポジトリ内のOpenAPI仕様です。

ステップ3: OpenAPI YAMLを編集する

Spec-Firstモードでは、生のOpenAPI YAMLを編集できます。構文ハイライト、インライン検証、自動補完により、IDEに近い操作感で仕様を更新できます。

例として、ヘルスチェック用のエンドポイントを追加します。

paths:
  /health:
    get:
      summary: Service health check
      operationId: getHealth
      responses:
        '200':
          description: Service is up
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
Enter fullscreen mode Exit fullscreen mode

編集すると、ApidogはYAMLを解析し、左側のアウトラインを更新します。/healthエンドポイントもツリーに表示されます。

また、以下のような問題はコミット前にインラインで確認できます。

  • responsesの不足
  • 不正な$ref
  • YAMLのインデントミス
  • OpenAPI仕様として不正な構造

YAMLが壊れている場合、CIや生成処理で失敗してから気づくのではなく、エディター上で早い段階に修正できます。

OpenAPI仕様の差分管理や履歴管理については、GitによるOpenAPIバージョン管理も参考になります。

ステップ4: コミットしてGitHubへプッシュする

編集が完了したら、変更をGitHubへ送信します。

  1. ApidogのGitまたはソース管理パネルを開きます。
  2. 変更内容を確認します。
  3. コミットメッセージを入力します。
    • 例: Add /health endpoint
  4. 「コミット＆プッシュ」をクリックします。

Apidogは、選択したブランチに対して通常のGitコミットを作成し、リモートへプッシュします。

GitHub側でリポジトリを確認すると、ブランチ履歴にコミットが表示されます。OpenAPIファイルのみが意図どおり変更されているか、通常のコードレビューと同じように確認できます。

プッシュ前に取り消したい場合は、未プッシュの編集を破棄できます。コミット＆プッシュするまでは、変更はリモートへ送信されません。

ステップ5: 同期ステータスを確認する

Apidogには同期ステータスが表示されます。

プッシュが成功すると、同期インジケーターは「今すぐ同期されました」のような状態になります。これは、Apidog上のエディターとリモートブランチのOpenAPI仕様が一致していることを示します。

時間が経つと、「5分前に同期されました」のように表示が更新されます。チームメイトが同じブランチに変更をプッシュした場合、Apidogはその変更を取り込み、同期状態を更新します。

インジケーターが保留中または古い状態を示している場合は、ローカルの編集内容とリモートブランチが分岐している可能性があります。その場合は、続行する前に最新状態を取得し、必要に応じて競合を解決してください。

トラブルシューティング

認証エラーでプッシュできない

OAuthトークンが期限切れになった、またはプロバイダー側で取り消された可能性があります。

対処:

  1. ApidogでGitプロバイダー接続を確認します。
  2. 必要に応じて再認証します。
  3. 対象リポジトリへの書き込み権限があるか確認します。

保護されたmainブランチへプッシュできない

GitHubのブランチ保護ルールにより、直接プッシュが拒否される場合があります。

対処:

  • 作業用ブランチを作成して同期します。
  • Pull Request経由でmainへマージします。
  • 必要に応じてブランチ保護ルールを見直します。

チームメイトの変更と競合した

同じOpenAPIファイルの同じ箇所を別の人が更新していると、Gitの競合が発生します。

対処:

  1. リモートの最新状態を取得します。
  2. 重複しているYAMLの変更を確認します。
  3. 通常のテキストファイルと同じように競合を解決します。
  4. 検証エラーがないことを確認します。
  5. 再度コミットしてプッシュします。

検証エラーがある

ApidogはYAMLやOpenAPI構造の問題をインラインで表示します。

対処:

  • インデントを修正します。
  • 必須フィールドが欠けていないか確認します。
  • $refの参照先が存在するか確認します。
  • responses、schema、contentの構造を確認します。

無効な仕様のまま進めると、生成ドキュメント、モック、テストの正確性に影響します。コミット前にできるだけクリーンな状態にしておくのが安全です。

FAQ

GitHubとの同期はGitLabおよびAzure DevOpsでも機能しますか？

はい。Spec-FirstモードはGitHubとGitLabを直接サポートします。Azure DevOpsはGit接続経由で利用できます。接続、編集、コミット、プッシュの基本フローは同じです。違いは主に認証画面とプロバイダー側の権限設定です。

Apidogで作業中にチームメイトがリポジトリ内の仕様を編集した場合、どうなりますか？

Apidogは双方向同期の一部として、リモート側の変更をエディターへ取り込みます。変更箇所が重複していなければ、そのままマージされます。重複している場合は、通常のGit競合として解決します。

GitHubに送信する前に変更を元に戻せますか？

はい。コミット＆プッシュするまでは、編集内容はリモートへ送信されません。未プッシュの編集を破棄すれば、ドキュメントを最後に同期された状態へ戻せます。

Top comments (0)