コントラクト テスト ツール「API Hub for Contract Testing」を使ってみよう！パート 1: プロバイダー側の操作

2025.07.12

この記事では、API Hub for Contract Testing を使って、コントラクト (契約) テストを開発ワークフローに統合して、デザイン ファーストの API 開発を実現する方法を全 3 パートのシリーズとして紹介します。

パート 1 となる本記事では、シリーズの概要、手順の実行に必要なもの、プロバイダー (API 提供者) 側の操作について説明します。

API Hub for Design UI 内で統合を設定するには、「API Hub for Design 統合ガイド」を参照してください。

このシリーズでは、開発ワークフロー全体を説明します。GitHub を使用してサンプル リポジトリをフォークし、GitHub Actions を使用して CI パイプラインを実行することで、ワークフローを簡略化します。

  1. OpenAPI 仕様を使用して API を作成し、ドキュメント化します。
  2. プロバイダー コントラクト (OpenAPI ドキュメント) を API Hub for Contract Testing に公開します。
  3. API コンシューマーを記述します。
  4. Mountebank、Nock、Wiremock、Cypress、Mock-Service-Worker などのツール、または従来の Pact .NET を使用して API クライアントのテストを記述し、API をモックして、モックをコンシューマー コントラクトに変換します。
  5. コンシューマー コントラクトを API Hub for Contract Testing に公開します。
  6. API Hub for Contract Testing の互換性のない変更検出システムについて学びます。

準備

以下のものが必要になります。

  • API Hub for Design アカウント
    無料版を利用できます。お持ちでない場合は、こちらから作成してください。
  • GitHub アカウント
    ここで紹介するすべてのサンプルは、Github Actions CI パイプラインで動作します。アカウントは無料作成できます。お持ちでない場合は、こちらから作成してください。
  • API Hub for Contract Testing アカウント
    双方向機能は API Hub for Contract Testing でのみサポートされるため、API Hub for Contract Testing のアカウントが必要です。

組織の共有の API Hub for Contract Testing アカウントを使用する場合

組織の共有の API Hub for Contract Testing アカウントを使用することもできますが、他のワークショップ参加者のものと競合しないように、作成されるさまざまリソースの識別子を変更する必要があります。そのため、各自のアカウントを使用することを推奨します。

プロバイダー側の操作

API デザイン

OpenAPI を使用して API を作成し、ドキュメント化します。

デザイン ファースト アプローチに従って API を開発するため、まず API の動作を定義した OpenAPI 仕様 (OAS) ドキュメントを作成します。

OAS ドキュメントの作成はこのチュートリアルの範囲外ですが、インターネットで多くのリソース (swagger.io など) を見つけることができます。

ここでは、サンプルの Product API を例に説明します。こちらから Product API の OpenAPI 定義を参照できます。

  1. POST /products – 新しい製品を作成します。
  2. GET /products – すべての製品を取得します。
  3. GET /product/:id – 1 つの製品を取得します。

Product のスキーマは以下の通りです。

product-schema-pf.png

API Hub for Design で OpenAPI ドキュメントを作成します。

  1. [Create New] > [Create New API] を選択します。
    PF_Screenshot_SwaggerHub_01
  2. [Owner] を選択します。
  3. [Specification] で [OpenAPI 3.0.x] を選択します。
  4. [Template] で [None] を選択します。
  5. [Name] に API の名前を入力します。
  6. [Version] で [1.0.0] を選択します。
  7. [Auto Mock API] をオンにします。
  8. [Create API] ボタンをクリックします。
  9. Product API の OpenAPI 定義をコピーしてペーストします。

これで、API Hub for Design を使って最初の API 定義を作成できました。

API Hub for Design で API を作成する方法については、こちらのガイドを参照してください。

プロバイダーのデザイン仕様を API Hub for Contract Testing に公開する

コントラクトの公開に関する詳細は、こちらを参照してください。

プロバイダーの仕様が完成したら、API Hub for Contract Testing を使ってコンシューマーと共有します。このステップは、プロバイダー コントラクトの「公開」と呼ばれます。

公開ステップには、2 つの主要なコンポーネントが含まれます。

  • プロバイダー コントラクト (この例では OAS ドキュメント)
  • テスト結果 (この例ではデザインをテストするだけなので、OAS ドキュメントを使用します。実装は作成後に別のフローでテストします。)

この情報は、後でコンシューマーとの互換性を確認する際に役立ちます。

  1. example-provider プロジェクトを自分の GitHub アカウントにフォークします (右上の [Fork] ボタンをクリックします)。
    example-provider.png
    1. フォークした example-provider プロジェクトを開きます (https://github.com/<ユーザー名>/example-provider)。
    2. .github/workflows/ProviderDesignFeedback.yml を開きます。
    3. ファイル ビューの右上にある 🖊️ をクリックして、ファイル エディターを開きます。
    4. PACT_BROKER_BASE_URL の値を、API Hub for Contract Testing アカウントのベース URL に更新します。ベース URL は、API Hub for Contract Testing の [API Tokens] ページにある [COPY PACTFLOW BASE URL] ボタンをクリックして取得できます。
      provider-design-feedback.png

    5. 次の行を削除します: if: ${{ github.repository_owner == 'pactflow' }}。
    6. 緑色の [Commit changes] ボタンをクリックします。
  2. API Hub for Contract Testing の API トークンを保存する GitHub Secret を作成します。
    1. API Hub for Contract Testing で以下の操作を行います。
      1. API Hub for Contract Testing アカウント (https://<サブドメイン>.pactflow.io) にログインし、[Settings] > [API Tokens] に移動します。ドキュメントはこちらを参照してください。
      2. 読み書き可能な CI トークンの [Copy] ボタンをクリックします (読み取り専用ではなく、読み書き可能なトークンであることを確認してください)。
    2. Github で以下の操作を行います。
      1. フォークした example-provider プロジェクト (https://github.com/<ユーザー名>/example-provider) に移動します。
      2. [Settings] タブをクリックします。
      3. サイドメニューから [Secrets] を選択します。
      4. [New repository secret] ([Actions secrets] 見出しの右側のボタン) をクリックします。
      5. シークレットの名前を PACTFLOW_TOKEN_FOR_CI_CD_WORKSHOP に設定します。
      6. 前の手順でコピーした API Hub for Contract Testing の API トークンの値をペーストします。
      7. [Add Secret] をクリックします。
        action-secrets.png

  3. [Actions] タブをクリックします。
  4. [I understand my workflows, go ahead and enable them] ボタンをクリックします。
  5. [Sync OpenAPI] > [SCM with Github Sync] を選択します。
    1. API Hub for Design で API ページを開きます。
    2. API 名をクリックして、[Integrations] タブに切り替えて、[Add New Integrations] をクリックします。
    3. [GitHub Sync] を選択します。
    4. 続くダイアログで統合パラメーターを指定します。
      1. [Name] – 必須。統合の表示名です。ここでは、gh-design-to-pactflow。
      2. [GitHub Token] – 必須。API Hub for Design が対象の GitHub リポジトリへのアクセスに使用する GitHub アクセス トークンです。
      3. トークンを取得する最も簡単な方法は、[Connect to GitHub] をクリックし、API Hub for Design が GitHub アカウントから情報を取得できるようにすることです。
      4. [GitHub Token] 編集ボックスで [Next] をクリックして続行します。API Hub for Design はトークンを検証し、その他のパラメーターを表示します。
      5. [Repository Owner] – 前の手順で作成したリポジトリを所有する GitHub ユーザーまたは組織を選択します。
      6. [Repository] – コードをプッシュするリポジトリを選択します。
    5. [Sync Method] – 同期の種類として「Basic Sync」を選択します。
    6. [Branch] – 必須。コードをプッシュするリポジトリのブランチです。ブランチが存在しない場合、リポジトリのデフォルトのブランチに基づいて作成されます。swaggerhub を選択します。
    7. [Generated API Code] – 必須。生成するコードの種類として「YAML(Resolved)」を選択します。
    8. [Output Folder] – oas を選択します。
    9. [Output File] – swagger.yaml を選択します。
    10. [Create And Execute] > [Done] を選択します。
      PF_Screenshot_SwaggerHub_05

プロセスを実行すると、ダッシュボードは次のようになります。

PF_Screenshot_CreateExampleProject_01

これで、最初の API 定義を API Hub for Contract Testing にアプロードできました。

デザインを安全に本番環境にデプロイできるか確認する

プロバイダーの仕様をデザインし、プロバイダー コントラクトを公開したら、アプリケーションを本番環境にデプロイできるかどうかを確認します。

API Hub for Contract Testing には、コンシューマーとの互換性をチェックする can_i_deploy という便利なツールがあります。

can-i-deploy コマンドは CI/CD ワークフローにおいて重要な役割を果たし、互換性のないアプリケーションが本番環境にデプロイされるのを防ぐステージ ゲートを追加します。

以下の図は、これまでのプロセスに関連する CI/CD パイプラインを例示したものです。

PF_Screenshot_DeployToProduction_01.png

プロバイダーを安全に本番環境にデプロイできるか確認する

次のコマンドを実行します。

can-i-deploy

現時点ではまだコンシューマーが存在しないため、このコマンドはパス (成功) するはずです。

api-definition.png

$ pact-broker can-i-deploy --pacticipant pactflow-example-consumer --version="1.0.0-21b1f7fdf6428bfb0f583e151d9893c230a1c555-design" --to-environment production Computer says yes \o/ There are no missing dependencies

API を使用するコンシューマーが存在する場合、後方互換性のない変更をリリースすることはできません。コンシューマーもこのコマンドを使用して、ターゲット環境 (この例は production) のプロバイダー API との互換性を確認できます。

実際の実装では、ここでプロバイダーを本番環境にデプロイします。デプロイが完了すると、API Hub for Contract Testing は、プロバイダーの新しいバージョンが環境にプロモートされたことを認識し、コンシューマーにこのバージョンのプロバイダー OAS が本番環境でサポートされていることを通知できます。コンシューマーは新しいバージョンの OAS のサブセットを使用する機能を追加し、安全にデプロイできるようになります。

can-i-deploy を使用してデザインをチェックすることで、デザイン変更が、デプロイまたはリリースされるすべてのコンシューマーと互換性があるかどうかを確認できます。これにより、可視性とフィードバックが迅速に得られます。

これまでの手順で、プロバイダーのビルドが成功し、can-i-deploy は本番環境にデプロイ可能であることを示しているはずです。

パート 1 では、シリーズの概要、手順の実行に必要なもの、プロバイダー (API 提供者) 側の操作について説明しました。

パート 2 では、コンシューマー (API 利用者) 側の操作について説明します。

この資料は、SmartBear の Web サイトで公開されている API Hub for Contract Testing University ドキュメントの「Design First With API Hub for Design」にある「Quick Start Guide with Github Actions」を参考に作成しました。

タイトルとURLをコピーしました