メインコンテンツまでスキップ

Apidogを使い回す

本文では、Apidogを利用し始めようとするユーザーに対して、コア機能を紹介します。 30分間ほどの所要時間が必要です。

Apidogが選ばれた理由​

開発チームがAPIの設計、管理、テストのために、Postman、Swagger、Stoplight、Jmeterなどのさまざまなツールを使用していることが多いことを観察しました。ただし、これらのツール間でのデータ同期とコラボレーションがないので、効率が大幅に下がる可能性があります。

開発チーム全体が単一のAPIツール内ですべての作業をやり遂げるのは、より良い解決策だろうと思っています。APIドキュメントが定義されている限り、バックエンド開発者はAPIを簡単に実装して自己テストを行い、フロントエンド開発者はAPIを簡単に呼び出してMockデータを使用し、テストエンジニアはAPIを直接テストしてテストケースを簡単に生成できたら、チーム協同作業の効率が大幅に向上できるのでしょう。

これこそ、私たちはApidogを始めたきっかけです。Apidogは、チームの協同作業のために設計されていて、APIの設計、開発、テスト、管理、ドキュメント生成やMockなどのことが実現され、今までにない包括的なAPIツールです。

Apidogとは​

Apidogは、API開発のためのオールインワンツールキットです。チーム全体が協力して、APIをより効率的かつ便利に作成するために開発されているものです。チームの各メンバーは、それを使って自分の問題解決を図ることができます。

apidog

Apidogは、APIの設計と開発をユーザーインターフェイスより優先する開発アプローチ（いわゆるAPIファーストアプローチ）を採用しています。このアプローチには、次のようないくつかのメリットがあります。

  1. Apidogを使用すると、チームの各メンバーは同時に作業を進んでサービス間で合意を達成することで、複数のAPIで同時に作業し、開発速度を大幅に向上させることができます。
  2. 自動化は、APIの定義ファイルのインポートツールを通して実現され、APIの開発と実行に必要な時間を短縮できます。
  3. 直感的なデザインと十分に文書化されたAPIドキュメントにより、開発者の優れたエクスペリエンスが保証されます。また、開発者が簡単にコードを使用・再利用し、新しい開発者をオンボードし、学習コストを減らすこともできます。
  4. コードが書かれる前にも、ほとんどの問題を解決することができるので、APIをアプリケーションに統合する際に問題を発生することを防ぐこともできます。

API設計者：APIの作成​

API設計者はApidogを使用して、APIを視覚的に作成するか、OpenAPIの仕様からインポートします。

OpenAPIの仕様からインポート​

APIがOpenAPIまたはその他の形式で指定されている場合は、Apidogにインポートすると、簡単にデバッグ、テスト、またはMockすることができます。

  1. Apidogのプロジェクトで インポートをクリックします。

Import

  1. URLのインポートを選択して、次のURLを貼り付けて、 提出をクリックします。
https://petstore.swagger.io/v2/swagger.json

apidog

JSONとYAMLファイルからのインポートも可能ですが、Apidog、HARなど、他のAPI仕様の形式もサポートされています。

  1. 確認をクリックしてインポートします。

apidog

  1. ここでApidogを使用してAPIを実行するか、テストすることができます。

apidog

ヒント

データのインポートの詳細を ここで見る。

新しいAPIを作成​

API設計者は非常に直感的なインターフェース内でAPIを作成できます。

  1. 新しいタブで 新しいAPI をクリックしてエンドポイントを作成します。

apidog

  1. 次に、IDでユーザー情報を照会するためのAPIを指定します。そのため、次のフィールドをAPIに入力できます。
    • APIパス：
      • /users/{id}
    • 名前：
      • IDでユーザー情報を取得

apidog

  1. このAPIには、QueryパラメータとBodyパラメータがありません。ここで「Id」がPathパラメータとして認識されると、「Request」の部分が完成しました。
  2. Response 部分に移動して、「OK (200)」でルートノードのフィールドタイプを「参照モデル → Schemas → ApiResponse」に変更します。

apidog

  1. ここでAPIは、次のような一般のJSON構造を生成しました。全てのAPIも異なる「data」フィールドがあるため、ルートノードに「data」と名付けられた子ノードを追加します。

apidog

  1. 「data」ノードのフィールドタイプを「参照モデル → Schemas → User」に変更します。

apidog

  1. ここでResponseをうまく設定できました。「data」構造内のデータを編集する場合は、スキーマ参照を解除するか、編集したいフィールドの参照を解除する必要があります。

apidog

ヒント

データSchemaの詳細を ここで見る。

  1. Responseの例の部分に移動して、 例を追加をクリックします。

apidog

  1. 例の名称を「Success」に設定します。ここで 自動生成をクリックして、戻りデータがResponse構造に基づいて生成されます。 OK をクリックして例を追加します。

apidog

  1. 保存をクリックして、APIの作成が完了しました。ここでうまく設計されたAPIが手に入れましたよ。

apidog

バックエンド開発者：APIの開発とデバッグ​

異なるチームは異なる開発アプローチを採用しています。APIファーストを採用しているチームもありますし、コードファーストを採用しているのもあります。ただし、チームがどの方法を採用していても、バックエンド開発者はApidogを使用してAPIの開発とデバッグを簡単に実現できます。

コードの生成​

  1. APIが指定された場合、 スタブサーバーとクライアントSDKが簡単に生成されます。APIページで コード生成 ボタンから すべてのコードを生成をクリックするだけです。

apidog

  1. OpenAPI Generatorエンジンを利用して、スタブサーバーとクライアントSDKを数十個の言語で生成できます。

apidog

ヒント

コード生成の詳細を ここで見る。

APIを実行​

APIの開発が完了すると、多くの場合ではバックエンドの開発者は、APIが異なるパラメータで正確な結果を返すかをデバッグする必要があります。Apidogを使用すると、各APIをデバッグし、正常に実行できることを簡単に確認できます。

  1. 先に作成したAPIのページで、 実行ボタンをクリックして 実行 タブに移動します。

apidog

  1. 「id」パラメータのパラメータ値で「1」を入力します。ここで送信待ちのrequest URLの中の {id} は、「1」に置き換えられます。

apidog

  1. 画面の右上角の 環境の管理ボタンをクリックします。

apidog

  1. 「テスト環境」に切り替えて、次のURLを「Default Sever」サービスに貼り付けます。その後、環境を保存します。
https://mock.apidog.com/m1/352945-0-default
ヒント

環境管理の詳細を ここで見る。

apidog

  1. そして、「Testing Env」を選択すると、先に設定したBase URLは、送信待ちのすべてのrequestsの先頭に追加されます。

apidog

  1. 送信をクリックしてRequestを送信します。APIのResponseは下の部分で表示されます。

apidog

デバッグ​

APIの開発が環境を設定した後、 バックエンド開発者は、期待のデータを返しているか、APIが正しいロジックを実装しているかをテストする必要があります。

  1. pathパラメータの値を「2」に設定して、 Requestを 送信します。

apidog

  1. 「$.data.id should be integer」という警告が表示されます。なぜかというと、$.data.idはintegerである必要がありますが、実際に返された$.data.idはStringになっているからです。

apidog

  1. Apidogは、APIの定義と実際のResponseが一貫しているかどうかを自動的に検証します。正しくないデータタイプ、定義されていない列挙値、必須フィールドの欠落などの問題は自動的に検出されます。バックエンド開発者は、戻りデータの問題を簡単に検出できます。
  2. APICaseを保存ボタンをクリックしてRequestを保存します。 当該RequestはAPIの子ディレクトリに保存され、テストモジュールに参照されることができます。

apidog

apidog

変数の利用​

Apidogでは、変数がRequest間で再利用可能な値を格納するために利用されています。

環境変数は環境に繋がっています。つまり、特定の環境が選択された場合にのみアクセス可能です。一方、グローバル変数は、すべての環境でアクセスできます。

Apidogの「環境の管理」セクションで環境変数を定義し、{{variableName}}のように二重波括弧を使用して、Requestで環境変数を参照できます。

例：

  1. pathパラメータ「id」の値に{{Userid}}を入力します。

apidog

  1. 環境管理をクリックします。 Useridと名付けられた変数を新しく追加し、 ローカル値に「1」を記入して、変数を保存します。

apidog

  1. Requestを送信します。 Response - 実際のRequestの順にrequest URLを確認できます。ここで {{Userid}} は ローカル値に置き換えられたことを確認できます。

apidog

ヒント

変数の詳細を ここを見る。

前処理​

Apidogでは、前処理はRequestを送信する前に実行される操作です。これにより、Requestが送信される前にRequestと環境変数を操作できます。

前処理の利用シーン：

  • Requestで利用されている変数の設定と編集
  • データ検証、またはデータ変換の実行
  • Headerの追加と編集
  • ログ情報とデータのデバッグ
  • 他のReuqestを行い、そのResponseデータを変数への保存
  • Request URLの編集

これらの操作はJavaScriptに書き込まれ、Postman SDKでRequest、Responseオブジェクト、環境変数、及びグローバル変数にアクセスできます。Scriptが追加されると、Requestが送信されるたびに実行されます。

前処理のRequestパラメータ値を変更する例：

  1. 前処理タブをクリックし、 前処理を追加 ボタンをクリックして カスタムScriptを追加します。

apidog

  1. 次のScriptを カスタムScriptエリアに貼り付けます。
let Userid = parseInt(pm.environment.get("Userid"));
Userid = Userid + 1;
console.log(Userid);
pm.environment.set("Userid", Userid);

apidog

  1. カスタムScript を 変数置換＆親を継承にドラッグして、Requestを送信します。

apidog

  1. 送信した後、 {{Userid}}の値が2になったことを確認できます。そして、Requestを複数回送信する場合、送信する度に、 {{Userid}} の値に1をプラスするようになります。

apidog

  1. 共通Script、データベース操作及び待機時間は、前処理に追加可能な項目です。

apidog

ヒント

Scriptの詳細を ここで見る。

フロントエンド開発者： APIのMock​

APIのMockは、テストと開発の目的で使用されるAPIのシミュレートされたバージョンです。これにより、開発者はライブAPIに依存せずにアプリケーションやサービスをテストでき、送信のRequestに特定のResponseを返すように構成できます。

指定されたAPIに基づいて、Apidogは設定なしでMockデータを自動的に生成できます。それはフロントエンド開発者にとって非常に便利な機能です。

  1. APIタブで ローカルMockを選択します.そして、 Click the URL/パラメータをクリックして、「OK(200)」をコピーします。

apidog

  1. ブラウザでURLを貼り付けます。そして、生成されたJSONが見えます。そのデータはダイナミックで、ページをリフレッシュする度にデータが変わります。

    特に、生成されたデータには、「email」や「lastName」のような項目があります。ご覧のように、これらの値は非常に合理的で現実みたいものになります。この機能は、Apidogの スマートMockと言います。

apidog

  1. 変更タブの Response 部分で 「ApiResponse」Schemaの 参照を解除 します。

apidog

  1. ノード内の各 Mock値を入力して、APIを 保存 します。
    • code
      • 200
    • type
      • JSON
    • message
      • Success

apidog

  1. ブラウザでページを再読み込みすると、JSONデータが更新され、「code」、「type」、および「message」フィールドが設定に従って生成されます。現在、フロントエンド開発者は単にURLを使用して、開発中のクライアントでデータを取得できるようになります。

apidog

  1. Mock設定は、Faker.jsをもサポートしています。任意のFaker.js文法を選択してダイナミックのMockデータを生成できます。

apidog

  1. MockのResponseを修正する必要がある場合、 設定 - 機能設定 - Mock設定 - デフォルトMockタイプの順にクリックし、 Response例を優先に切り替えます。ApidogのMockエンジンは、 API Responseの例をMockのResponseとして使用します。

apidog

ヒント

ApidogのMock機能は、クラウドMockもサポートし、さまざまなRequestパラメータに対して異なるMock Responseを返したり、Scriptを使用してMockのResponseを書き換えたり、賢いMockマッチングルールをカスタマイズしたりすることができます。 Mockの詳細を ここでを見る。

QAエンジニア：APIのテスト​

Apidogの自動テストモジュールにより、QAエンジニアはAPIの定義またはAPIケースを参照して、テストのシナリオを直接に生成できます。データ駆動型テストをサポートし、ダイナミックのテストデータを簡単に生成できます。また、アサーションと変数抽出機能により、テストケースの作成を非常に簡単にしました。ApidogはCI/CDもサポートしています。

アサーション​

Apidogでは、後処理でサーションを追加することができます。また、Postman SDKを使用してカスタムスScriptでアサーションステートメントを追加することもサポートしています。

  1. Get user by id - Successという保存ケースに移動して、 後処理 タブで 後処理を追加 - アサーションの順にクリックします。

apidog

  1. アサーションで次のパラメータを設定します：
    • Response JSON
      • $.code
    • Assertion
      • 等しくない： 200
ヒント

JsonPathの詳細を ここで見る。

apidog

  1. Reuqestを送信すると、アサーション結果を確認できます。

    Apidogは、Response JSONから$.codeの値を取得して、アサーションと比較します。マッチングする場合、アサーション結果は合格になります。

apidog

  1. 後処理では、変数抽出, カスタムScript, 共通Script, データベース操作と 待機時間も追加されることができます。

    MySQL、SQL Server、Oracle、PostgreSQL、およびClickHouseデータベースは、Apidogでサポートされています。SQLステートメントを実行でき、SELECT結果を変数に抽出できます。INSERT、DELETE、UPDATEなどの他のSQLも実行できます。

apidog

ヒント

データベース操作の詳細を ここで見る。

シナリオテスト​

アサーションを書いた後、複数のAPIケースを同じ単一のテストケースにインポートし、1クリックで実行してテストレポートを生成します。

  1. 自動テストモジュールにアクセスして、 新規テストケースを作成します。

APidog

  1. 当該ケースの設定を終了してそれにアクセスします。 ステップを追加をクリックして、 APIテストケースからインポートするを選択します。

APidog

  1. テストのステップとして、保存したAPICaseを選択して、「確認」をクリックしてインポートします。

APidog

  1. テストケースを行うには、 実行ボタンをクリックします。そして、詳細なテストレポートが作成され、各Requestの詳細を確認することができます。

apidog

  1. 失敗した項目で 詳細をクリックし、Responseとアサーションを比較して、うまく行かなかった原因をチェックできます。

apidog

apidog

ヒント

テストケースの詳細を ここで見る。

データ駆動型テスト​

APIケースで変数が使用される場合、データテーブルか「動的値」機能を使用して変数の値を自動的に生成するように設定できます。

  1. テストデータをオンにして、 テストデータを管理するをクリックします。

apidog

  1. 変数とデータベースを追加し、変数の値も設定します。ここでCSVかJSONからインポートすることもサポートされます。保存をクリックして、テストデータの設定を保存します。

apidog

  1. ここテストデータを利用するかを選択して 実行します。変数の値は、テストケースの反復で使用されます。

apidog

ヒント

テストデータの詳細を ここで見る。

CI / CD​

Apidogはコマンドラインでの実行をサポートしています。Apidog CLIをインストールした後、apidog runコマンドを使用してコマンドラインのテストレポートを取得できます。このコマンドは、Jenkinsでも利用して、CI/CDを実装できます。

  1. テストケースで「CI/CD」をクリックします。

Apidog

  1. テストのパラメータを設定して保存すると、コマンドラインが生成されます。ここで さらに詳しくをクリックしてApidog CLIをインストールします。

apidog

ヒント

CI / CDの詳細を ここで見る。

APIの設計者 & APIユーザー: APIドキュメント​

APIの設計、開発、デバッグ、テストが終了すると、APIは、他のユーザーが利用できるプロダクトになります。Apidogは綺麗なAPIドキュメントを生成できるため、開発チームはAPIを公開する時に役立ちます。

  1. 共有モジュールにアクセスし、 +新しい共有から共有項目を作成します。

apidog

  1. APIドキュメント実行環境を選択すると、APIドキュメントの利用者は、ここで設定された環境を使用してAPIを実行できます。

apidog

  1. 「開く」をクリックして共有対象となるドキュメントをブラウザで開きます。

apidog

  1. APIドキュメントが生成され、インターネット上で共有できます。また、共有したWebサイトで「送信」することもできます。

APidog

  1. コードのサンプル機能は、APIのRequestコードを数十個のプログラミング言語で生成できます。そして、APIリーダーが生成されたコードで直接にAPIを呼び出すことが可能になります。

APidog

  1. Responsesのコード生成 機能は、Responseデータの構造に従ってコードを生成できます。数十個のプログラミング言語がサポートされ、API利用者は、生成されたコードを直接に実装の段階で使用できます。

apidog

apidog

  1. ドキュメント機能では、カスタムドメイン、 上部のナビゲーション、 カタログのスタイル, コンテンツのフッターなど、他にも多くのカスタム機能はサポートされています。

apidog

ベストプラクティス​

1.Apidogでは、API設計者(またはバックエンド開発者)がAPIの仕様を定義します。

2.開発チームは協力して、ドキュメントをレビュー＆改善し、APIユースケースの一貫性を確保します。

3.Apidogを使用すると、フロントエンド開発者は自動的に生成されたMockデータで開発を開始でき、手動でMockルールを作成する必要はありません。

4.バックエンド開発者は、開発中にAPIユースケースを使用してデバッグできます。デバッグ中にすべてのAPIユースケースが合格した場合、開発完了。また、開発中にAPIの変更がある場合、APIドキュメントもデバッグ中に自動的に更新され、最小限の手間で適時にAPIメンテナンスを行えます。

5.デバッグ後、バックエンド開発者はAPIユースケースとして機能を簡単に保存できます。

6.QAエンジニアは、APIユースケースを使用してAPIを直接にテストできます。

7.すべてのAPIが開発されると、QAエンジニア(またはバックエンド開発者)は、テストケースとテストコレクション機能を使用して、全面的に複数のAPIインテグレーションテストを実施できます。

8.フロントエンドとバックエンド開発の共同デバッグは、両方のチームが同じなAPIの仕様に準拠しているため、フロントエンド開発者がMockデータから実際のデータに切り替える時にも、通常問題が発生しません。

9.API開発が完了すると、Apidogは綺麗なAPIドキュメントを生成し、開発チームがAPIを外部チームに簡単に公開できます。

上記は、Apidogのコア機能と操作ガイドの概要です。Apidogには、開発チームがAPIを効率的に開発してデバッグするのに役立つ機能がたくさん備えていますので、今すぐApodogの使用を開始して探索し始めましょう。