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

2025.07.12

API Hub は 2025 年 11 月に Swagger に名称が変更されました。

これに伴い、各コンポーネントの名称も以下の通り変更されました。
・API Hub for Design → Swagger Studio
・API Hub for Contract Testing → Swagger Contract Testing
・API Hub for Portal → Swagger Portal
・API Hub for Explore → Swagger Explore
・API Hub for Test → Swagger Functional Testing

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

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

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

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

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

準備

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

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

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

組織の共有の Swagger 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

Swagger Studio で 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 定義をコピーしてペーストします。

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

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

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

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

プロバイダーの仕様が完成したら、Swagger 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 の値を、Swagger Contract Testing アカウントのベース URL に更新します。ベース URL は、Swagger Contract Testing の [API Tokens] ページにある [COPY PACTFLOW BASE URL] ボタンをクリックして取得できます。
      provider-design-feedback.png

    5. 次の行を削除します: if: ${{ github.repository_owner == 'pactflow' }}。
    6. 緑色の [Commit changes] ボタンをクリックします。
  2. Swagger Contract Testing の API トークンを保存する GitHub Secret を作成します。
    1. Swagger Contract Testing で以下の操作を行います。
      1. Swagger 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. 前の手順でコピーした Swagger 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. Swagger Studio で API ページを開きます。
    2. API 名をクリックして、[Integrations] タブに切り替えて、[Add New Integrations] をクリックします。
    3. [GitHub Sync] を選択します。
    4. 続くダイアログで統合パラメーターを指定します。
      1. [Name] – 必須。統合の表示名です。ここでは、gh-design-to-pactflow。
      2. [GitHub Token] – 必須。Swagger Studio が対象の GitHub リポジトリへのアクセスに使用する GitHub アクセス トークンです。
      3. トークンを取得する最も簡単な方法は、[Connect to GitHub] をクリックし、Swagger Studio が GitHub アカウントから情報を取得できるようにすることです。
      4. [GitHub Token] 編集ボックスで [Next] をクリックして続行します。Swagger Studio はトークンを検証し、その他のパラメーターを表示します。
      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 定義を Swagger Contract Testing にアプロードできました。

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

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

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

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

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

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

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

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 との互換性を確認できます。

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

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

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

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

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

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

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