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

GitリポジトリにOpenAPIドキュメントがありながら、APIクライアント内で編集している場合、その手間はよくご存知でしょう。YAMLをコピーして貼り付け、他の誰もそのファイルに触れていないことを願い、インポートがこっそりフィールドを削除していないことを祈るばかりです。仕様とリポジトリを手動で一致させ続けるのは、急いでいるときに限って問題が起きるような面倒な作業です。

このガイドでは、ApidogのSpec-Firstモードを使用してOpenAPI仕様をGitHubと同期する方法を説明します。これにより、リポジトリ内の仕様とエディター内の仕様が、常に調整が必要な2つのコピーではなく、同じものとして保たれます。プロバイダーを接続し、リポジトリから直接プロジェクトを開き、YAMLを編集して、変更を一度にGitHubにプッシュする手順を紹介します。同様の手順はGitLabでも機能します。

始めましょう。

双方向同期が意味するもの

双方向同期とは、編集が自動的に両方向に流れ、途中にエクスポートの手順がないことを意味します。

• ApidogからGitへ：ApidogでOpenAPIドキュメントを編集してコミットすると、選択したブランチに通常のGitコミットとして変更がリポジトリにプッシュされます。
• GitからApidogへ：チームメイト（またはあなた自身がIDEから）そのブランチに変更をプッシュすると、Apidogはそれをプルしてエディターがリポジトリの実際の状態を反映するようにします。

リポジトリが唯一の真実の源です。Apidogはその上に存在する豊富な機能を持つエディターです。それが、GitネイティブAPIワークフローの全体的な考え方です。仕様は、定期的にスナップショットをエクスポートするツール内に留まるのではなく、コードベース内の他のファイルと同じようにバージョン管理され、レビューされ、履歴が追跡されます。

前提条件

開始する前に、以下のものがあることを確認してください。

• Apidogがインストールされており（デスクトップアプリまたはウェブ）、サインインしていること。
• OpenAPIドキュメントが既に含まれているGitHubまたはGitLabリポジトリ、または書き込みアクセス権を持つリポジリ。Azure DevOpsもGit接続経由でサポートされています。
• Spec-Firstモード（ベータ版）が有効になっていること。これは、Apidog独自のストレージではなく、Gitリポジトリの薄いレイヤーとしてプロジェクトを機能させるモードです。

同期する予定のブランチには書き込み権限が必要です。読み取り専用アクセスではプルはできますが、プッシュはできません。

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

まず、Apidogがプロバイダーと通信できるように認証します。

1. Apidogを開き、Spec-Firstモードを選択して新しいプロジェクトを作成します。
2. ソースを選択するよう求められたら、プロバイダーとしてGitHubまたはGitLabを選択します。
3. 「認証」をクリックします。ブラウザでプロバイダーのOAuth画面が開きます。
4. 同期したいリポジトリへのApidogのアクセスを許可します。GitHubでは、アカウント全体ではなく特定のレポジトリにこれを限定できます。

認証が完了すると、プロバイダーが接続された状態でApidogに戻ります。これはプロバイダーごとに一度行うだけで、将来のプロジェクトはこの接続を再利用します。

Azure DevOpsをGit接続経由で含むこのフローの詳細については、Spec-Firstモードのドキュメントを参照してください。

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

次に、Apidogに実際の仕様を指示します。

1. プロバイダーが接続されたら、OpenAPIファイルを保持しているリポジトリを選択します。
2. 同期するブランチを選択します。通常はmainです。これは、コミットが着地するブランチであり、Apidogが受信変更を監視するブランチです。
3. Apidogが尋ねた場合、OpenAPIドキュメントへのパスを確認します（例：リポジトリのルートにあるopenapi.yaml、またはdocs/配下）。
4. プロジェクトを作成します。

Apidogはそのブランチから仕様をクローンし、開きます。Apidogがドキュメントをナビゲーション可能なアウトラインに解析するため、左側のサイドバーにはエンドポイントとスキーマが入力されます。これで、リポジトリの仕様をリアルタイムで見ていることになります。

ステップ3: コードエディターでOpenAPI YAMLを編集する

Spec-Firstモードは、構文ハイライト、インライン検証、自動補完機能を備えた、生のOpenAPI YAML用のIDEスタイルのエディターを提供します。OpenAPIを直接記述すると、Apidogは入力に合わせて視覚的なアウトラインを更新します。

小さなエンドポイントを追加してみましょう。ヘルスチェックを希望するとします。

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

入力すると、2つのことが起こります。左側のサイドバーがアウトラインを自動的に解析し、新しい/health操作がすぐにツリーに表示されます。そして、コミットする前に、バリデーターがresponsesブロックの欠落、不正な$ref、インデントのずれなどの問題をインラインで指摘します。YAMLの形式が不正な場合、後でパイプラインの失敗で発見するのではなく、下線で表示されます。

ここでバージョン管理がその真価を発揮します。仕様における差分や履歴がどのように機能するかをさらに詳しく知りたい場合は、GitによるOpenAPIバージョン管理に関するガイドを参照してください。

ステップ4: コミットとプッシュ

編集内容が正しいように見えたら、GitHubに送信します。

1. コミットパネル（プロジェクトのGit/ソース管理領域）を開きます。
2. 変更を確認します。Apidogは同期されたバージョンとの変更点を示します。
3. コミットメッセージを記述します。通常のコミットと同様に扱います。例：Add /health endpoint。
4. 「コミット＆プッシュ」をクリックします。

Apidogは選択したブランチにコミットし、リモートにプッシュします。GitHubでリポジトリを開くと、ブランチ履歴にコミットが表示され、期待どおりにOpenAPIファイルのみが変更されていることが確認できます。

プッシュする前に気が変わりましたか？未プッシュの編集を破棄して、ドキュメントを最後に同期された状態に戻すことができます。コミットするまでApidogから何も送信されないため、ローカルでの実験はローカルに留まります。

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

Apidogは同期インジケーターを表示するため、常に現在の状況を把握できます。

正常にプッシュされた後、インジケーターは「今すぐ同期されました」と表示されます。これは、エディターとリモートブランチが同じドキュメントを保持していることの確認です。時間が経つと「5分前に同期されました」のように更新され、他の誰かがプッシュした場合、Apidogはその変更をプルし、調整後にインジケーターをリセットします。

インジケーターが保留中または古い状態を示している場合、ローカルコピーとリモートが分岐していることを意味しており、続行する前にプルまたは解決すべきという合図です。

トラブルシューティング

初めての際に人々がつまずきがちな点がいくつかあります。

• 認証の期限切れまたは取り消し。権限エラーでプッシュが失敗し始めた場合は、ステップ1から認証を再実行してください。トークンはプロバイダー側で取り消されるか、単にタイムアウトすることがあります。
• 間違ったブランチ。プルリクエストを必要とする保護されたmainブランチへのプッシュは拒否されます。作業ブランチに同期するか、ブランチの保護ルールを調整してください。ステップ2で選択したブランチが、コミットが着地することを期待する場所と一致していることを再確認してください。
• マージの競合。あなたが編集している間にチームメイトが同じブランチにプッシュした場合、リモートがローカルコピーよりも進んでいます。最新の状態をプルし、重複するYAMLを調整して、再度コミットしてください。仕様はプレーンテキストであるため、競合は他のコードの競合と同じように解決されます。
• 検証エラーがワークフローを妨げる。Apidogは無効なYAMLのコミットを止めませんが、まずインラインバリデーターが指摘する問題を修正すべきです。クリーンな仕様は、生成されたドキュメント、モック、テストを正確に保ちます。

FAQ

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

はい。Spec-FirstモードはGitHubとGitLabを直接サポートし、Azure DevOpsはGit接続経由でサポートします。接続、編集、コミット、プッシュのフローは3つすべてで同じです。プロバイダーによって認証画面のみが異なります。

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

Apidogは双方向同期の一環として、彼らの変更をエディターにプルバックします。あなたの編集と彼らの編集がファイルの異なる部分に触れている場合、それらはきれいにマージされます。重複している場合は、任意のテキストファイルで行うのと同じように、標準的なGitの競合を解決します。

GitHubに到達する前に変更を元に戻すことはできますか？

はい。コミット＆プッシュをクリックするまでは、あなたの編集はローカルに留まります。未プッシュの編集を破棄すると、ドキュメントを最後に同期された状態に戻すことができ、何もリモートに到達しません。