GitネイティブなAPIテストと開発の連携

OpenAPI仕様は、APIとそのコンシューマー間の契約です。しかし、その契約はどこに存在しているのでしょうか？

API仕様は、多くの場合、分離されたツールに置かれがちです。一度エクスポートされると忘れ去られ、実装が変更されてもほとんど更新されません。ドキュメントは乖離し、テストコレクションは分岐します。レビュアーは、対応する仕様の更新を見ることなくコードの変更を承認してしまいます。

Spec-firstモードはこのモデルを覆します。OpenAPIまたはSwaggerファイルが真の情報源となり、実装コードとともにGitリポジトリに直接保存されます。すべての仕様変更は、既に利用しているのと同じブランチ、プルリクエスト、レビュープロセスを経由します。API設計、テスト、ドキュメントはすべて自動的に同期された状態に保たれます。

このチュートリアルでは、ApidogでSpec-firstプロジェクトをセットアップし、チームと仕様を編集し、Gitワークフローとすべてを同期させる方法を順を追って説明します。

Spec-firstモードとは？

一般的なAPIプロジェクトでは、ビジュアルフォームを通じてエンドポイントを作成するか、既存の仕様を開始点としてインポートします。ツールはAPI定義を内部に保存し、Git連携（利用可能な場合）はエクスポートステップとして機能します。

Spec-firstモードは異なります。主なワークスペースはファイルベースです。

• `openapi.yaml` または `openapi.json` がリポジトリに存在します。
• Apidog はこれらのファイルをパースし、ナビゲート可能なAPI構造を生成します。
• ファイルを直接（またはサポートされているフォームを通じて）編集します。
• 変更は自動的にGitに同期されます。

仕様ファイルは常に権威的なものです。Apidogはそこから読み込み、そこに書き込み、リポジトリと同期させます。

前提条件

このチュートリアルに従うには、以下が必要です。

• Apidogアカウント（無料プランで可）
• OpenAPI/Swaggerファイルを含むGitリポジトリ、または新規開始用の空のリポジトリ
• リポジトリへの書き込みアクセス権
• OpenAPIまたはSwagger構文に関する基本的な知識

ステップ1：Spec-firstプロジェクトの作成

Apidogで+ New Projectをクリックし、プロジェクトタイプとしてSpec-first Modeを選択します。

次に、Gitプロバイダーを接続します。

1. プロバイダー（GitHub、GitLab、Azure DevOps、またはBitbucket）を選択します。
2. 組織またはワークスペースを選択します。
3. 既存のリポジトリを選択するか、新しいリポジトリを作成します。
4. 同期のためのメインブランチを選択します。

Apidogはリポジトリのデフォルトブランチと同期します。それが`main`という名前でなくても、Apidogは自動的に適応します。

ステップ2：Webhook同期の設定（推奨）

セットアップ中に、webhookをインストールするオプションが表示されます。これにより、チームがリポジトリにプッシュするたびに自動同期が可能になります。

注: Webhookのインストールには通常、リポジトリに対する管理者権限が必要です。管理者権限がない場合はこのステップをスキップしてください。Git Pullを使用して手動で同期することは可能です。

Webhookの利点：

• チームが変更をプッシュ → Apidogが自動的に同期
• 手動での更新は不要
• 全員が最新の仕様の状態を確認できる

最初にwebhookのセットアップをスキップした場合でも、後からProject Settings > Git & Branchesから追加できます。

ステップ3：スペックワークスペースの探索

プロジェクト作成後、Specsワークスペースが開きます。これはファイルベースの編集とGit操作の中心ハブです。

3つのパネルが連携して機能します。

構造ツリーでエンドポイントをクリックすると、Apidogはソースファイル内の対応するセクションをハイライト表示します。タブを切り替えることなく、高レベルのAPIビューから低レベルのYAMLに移動できます。

ステップ4：仕様ファイルの編集

コードビュー：直接編集

YAML、JSON、Markdownなどのほとんどのファイルでは、コードビューを使用して生のテキストを編集します。

編集内容はファイルに残ります。Apidogはそれらを変換したり、個別に保存したりしません。仕様ファイルは単一の真の情報源であり続けます。

フォームビュー：構造化編集

サポートされているOpenAPIノード（エンドポイント、スキーマ、定義、API概要）については、フォームビューに切り替えます。

フォームビューは、次のような場合に便利です。

• YAML構造を覚えることなく、必要なすべてのフィールドを持つエンドポイントを追加する
• スキーマを視覚的に編集する
• セキュリティ定義やAPIメタデータを更新する

ノードがフォーム編集をサポートしていない場合、Apidogはコードビューを維持します。

ステップ5：即座に検証とプレビュー

Spec-firstモードには、リアルタイムの検証とドキュメントプレビューが含まれており、外部ツールは不要です。

検証で問題を確認する

エディターヘッダーのValidationをクリックします。パネルに現在の仕様のすべての警告とエラーが表示されます。

バッジには問題の総数が表示されます。次の問題が検出されます。

• 構文エラー
• 必須フィールドの欠落
• スキーマ違反
• 命名規則の問題

コミットする前に問題を修正してください。チームのレビュアーはこれらを手動で特定する必要がなくなります。

ドキュメントをプレビューする

Previewをクリックすると、仕様がAPIドキュメントとしてどのようにレンダリングされるかを確認できます。

エンドポイントの場合、プレビューには2つのタブが含まれます。

スキーマと定義の場合、プレビューにはレンダリングされたドキュメントビューが表示されます。

検証とプレビューは同じサイドパネルを共有します。一方を開くと他方は自動的に閉じます。

ステップ6：チームからの更新をプルする

共同作業者がリポジトリに変更をプッシュしたら、それらをApidogに取り込みます。

1. Specsワークスペースを開きます。
2. サイドバーで現在のブランチ名をクリックします。
3. Git Pullを選択します。

Webhook同期がアクティブな場合、Apidogはリポジトリのプッシュイベント時に自動的にプルします。手動での操作は不要です。

ステップ7：変更をコミットしてプッシュする

Apidogでファイルを編集した後、更新内容をGitに送り返します。

1. Specsワークスペースで変更を行います。
2. サイドバーのChangesをクリックして、変更、追加、名前変更、削除されたファイルを確認します。
3. Commit & Pushをクリックします。
4. 含めるファイルを選択します。
5. コミットメッセージを記述します。
6. Pushをクリックします。

これで、仕様の更新は、コード変更と同じプルリクエストワークフローに現れます。チームメイトは、実装とAPIコントラクトの両方を一箇所でレビュー、コメント、承認できます。

ヒント: プッシュする前にローカルの編集を破棄したい場合は、Discard all changesを使用してください。

ステップ8：ブランチでの作業

Spec-firstモードは、ブランチベースの完全なコラボレーションをサポートしています。ApidogはGitブランチをプロジェクトブランチにマッピングし、仕様のバージョン間を切り替えることができます。

一般的なブランチ操作

ブランチ管理は、Gitで期待されるものと同じように機能します。機能ブランチ、リリース、並行開発はすべて正しく同期されます。

ステップ9：CI/CDとの連携

仕様がGitに存在するため、自動化パイプラインに自然に組み込むことができます。

• Apidogの検証またはSpectralのようなツールを使用して、すべてのPRで仕様をLintする
• 仕様がメインにマージされたときにドキュメントを自動生成する
• 仕様変更によってAPIテストを実行する
• APIゲートウェイ、モックサーバー、SDKジェネレーターなどのダウンストリームシステムに同期する

GitHub Actionsワークフローの例：

name: Validate and Test API Spec

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint OpenAPI Spec
        run: npx spectral lint openapi.yaml

      - name: Run API Tests
        run: apidog run tests --spec openapi.yaml

API仕様は、アプリケーションコードと同じ品質ゲートを通過するようになりました。

代替案：ストレージバックアッププロジェクト

外部Gitリポジトリを接続する準備ができていない場合は、ApidogがストレージバックアップのSpec-firstプロジェクトを提供します。

これらのプロジェクトはApidogの内部ストレージを使用しますが、引き続き以下を提供します。

• ファイルベースの編集
• 検証とプレビュー
• ブランチ管理

UIのラベルはわずかに調整されます。

• Git PullはSyncになります
• Commit & PushはSaveになります

チームが準備でき次第、外部Gitに移行してください。

まとめ

Spec-firstモードを使用すると、APIワークフローは次のようになります。

Spec-firstモードは、OpenAPIファイルを本来あるべき契約、つまりバージョン管理され、レビューされ、常にコードと同期した状態にします。

試してみませんか？ApidogでSpec-firstプロジェクトを作成し、最初のリポジトリを接続してください。