ApidogのAPI設計・テスト・文書化・共有管理ガイド

はじめに

プロジェクト開発において、APIの作成、管理、テスト、ドキュメント化は非常に重要かつ困難なタスクです。そのため、効果的なAPI管理ツールの選定は、チームの生産性と協力効率を高めるための鍵となります。

この記事を通じて、以下のことが学べます：

1. Apidogの位置付けと利点
2. ApidogでどのようにAPIを素早く作成、共有、管理するか
3. Apidogがチーム協力にどのように役立つか

なぜApidogを使うのか

業界の課題

これまでは、ほとんどの開発チームが複数のツールを使用してAPIを管理していました。例えば：

• Swaggerを使ってAPIドキュメントを管理
• PostmanでAPIのデバッグ
• Mock.jsなどでAPIデータをモック
• JMeterでAPIの自動化テスト

このような作業フローでは、異なるツール間でデータの一貫性を保つことが非常に難しく、効率が悪いだけでなく、システム間の不一致が原因でチーム内の協力が低下することがよくあります。これにより、開発者とテスト担当者は非常に多くの問題に直面していました。例えば：

• 1.バックエンドエンジニアがSwaggerでAPIドキュメントを作成した後、Postmanで再度APIを設定する必要がある
• 2.APIモジュールやAPIの数が増える中、SwaggerではAPIドキュメントの管理が難しく、フロントエンドエンジニアは目的のAPIを探すのに時間がかかる
• 3.フロントエンドエンジニアがMock.jsでモックデータを作成する際、手動でモックルールを設定しなければならない
• 4.フロントエンドエンジニアはMock.jsのモックデータを使って開発を進め、バックエンドエンジニアはSwaggerで定義されたAPIを基に開発を行うが、両者の間で仕様変更や情報の共有が不十分なため、最終的に連携時に不一致が発生してしまう
• 5.テスト担当者はJMeterでテストケースを実行しているとき、APIに変更があった場合に、再度JMeterでAPIパラメータを設定し直さなければならない

これらの問題が長期的に積み重なり、開発サイクルが複雑化して、チーム全体が非効率的な作業を強いられることになります。Apidogはこのような問題を効果的に解決するためのツールです。

Apidog課題解決の方法

Apidogの位置付け

Apidogは、APIのドキュメント作成、デバッグ、モック、テストを一体化したコラボレーションプラットフォームです**。簡単に言うと、「Postman」＋「Swagger」＋「Mock」＋「JMeter」の機能を一つのツールで提供します。

これにより、複数のツールを使用する必要がなく、データの整合性を確保したまま作業が進められます。APIドキュメントを定義すれば、APIのデバッグ、モックデータ、テストがそのまま利用可能になり、重複作業を避けることができます。Apidogのクラウド版（SaaS版）は、無料で無制限に利用でき、日常的な業務において非常に便利です。

Apidogの主な機能

• 1.チーム管理機能：Apidogのチーム管理機能により、複数人でのプロジェクト協力がスムーズに行えます。チームごとにプロジェクトを管理し、メンバー間でデータを分けて作業できます
• 2.APIドキュメントの定義：ApidogはOpenAPI 3.0（旧Swagger）やJSON Schemaの規格に準拠し、視覚的に管理できるドキュメント作成機能を提供します。非常に使いやすく、学習コストが低いのが特徴です
• 3.APIデバッグ機能：Postmanと同様の機能（環境変数、事前スクリプト、後処理スクリプト、クッキー/セッションのグローバル共有）が完備されており、直感的にAPIのデバッグが行えます
• 4.データモック機能：内蔵のMock.jsエンジンにより、簡単にデータをモックすることができます。APIのレスポンスをモックするだけでなく、リクエストパラメータに基づいて異なるデータを返すように設定できます。設定なしで非常に直感的にモックデータを生成できます
• 5.自動化テスト機能：JMeterのような自動化テスト機能を提供し、APIコレクションを選択するだけでテストセットを作成できます。自動化テスト機能もPostman並みに強力であり、使いやすさも向上しています

Apidogの基本的な使い方

Apidogは、使いやすさと直感的なインターフェースを兼ね備えたAPI管理ツールです。ここでは、Apidogの主要な機能とその使い方について、スクリーンショットを交えて簡単に紹介します。

1. チーム管理

Apidogでは、「チーム」は協力と組織の中心的な単位です。各チームには複数のプロジェクトとメンバーを含むことができ、チーム間のデータは互いに独立しており、可視性もありません。これにより、データの分離性が確保されます。

チーム機能の主な内容には、メンバー管理、権限管理、コラボレーションがあります。チームメンバーをチームに招待し、それぞれに異なる役割と権限を割り当てることができます。これにより、プロジェクトとデータの安全性が確保されます。チームメンバーはリソースを共有したり、共同編集やディスカッションを行ったりすることができ、チームの協力効率やプロジェクトの完成度が向上します。

まず「私のチーム」->「新規プロジェクト」で「テスト」という名前のチームを作成します。

チームが作成できたら、プロジェクトチームの開発メンバーを招待できます。開発メンバーがプロジェクト開発で果たす役割に注意する必要があります。Apidogでは、権限の階層はチームの役割とプロジェクトの権限に分かれています。チームの役割には、チームオーナー、チーム管理者、チームメンバー、ゲストがあり、それぞれの役割に対応する権限は以下の通りです：

権限名	チームオーナー	チーム管理者	チームメンバー	ゲスト
チーム情報の編集	✅	❌	❌	❌
チームの譲渡	✅	❌	❌	❌
チームの解散	✅	❌	❌	❌
メンバーの権限リストを表示	✅	✅	❌	❌
メンバーの権限を変更	✅	✅	❌	❌
メンバーの招待／削除	✅	✅	❌	❌

例えば、プロジェクトのバックエンド開発者を招待したい場合、彼には「チーム役割」を「チームメンバー」に設定し、プロジェクト権限を「管理者」に設定する必要があります。バックエンド開発者は、APIドキュメントの作成・管理などの機能を利用する必要があり、外部APIをインポートする機能も活用して、プロジェクトのインターフェースを迅速にメンテナンスするためです。そのため、プロジェクトレベルでの権限は、少し高いものが必要です。

注意すべき点は、メンバー招待リンクを送信する際には、招待するメンバーの「チーム権限役割」を選択することができないことです。デフォルトでは「チームメンバー」に設定されます。同時に、プロジェクト権限はすべてのプロジェクトに対して割り当てられるため、チームメンバーを招待した後、実際のプロジェクトの状況に応じて、異なるメンバーに異なるチーム権限とプロジェクト権限を割り当てる必要があります。

2. プロジェクト管理

Apidogで複数のプロジェクトを簡単に管理できます。プロジェクトごとにAPIの設計やテストケースを分けて整理することができ、効率的な開発が可能になります。

操作方法：
「チームプロジェクト」->「新規プロジェクト」->「作成」を通じて、「テスト」という名前のプロジェクトを作成します。ここで注意すべき点は、プロジェクトの作成者は「チームオーナー」または「チーム管理者」のみであることです。また、プロジェクトを削除すると元に戻せないため、チームメンバーの権限の割り当てには十分注意する必要があります。

3. 通知管理

前述のように、API ドキュメントが変更された場合、バックエンドエンジニアはフロントエンドエンジニアに口頭で伝えるか、他の手動の方法で通知しなければならないことがありますが、口伝えでは情報が漏れることがあります。このような状況では、Apidog は「通知設定」機能の使用を推奨します。

Apidog では、サードパーティー統合機能をサポートしており、通知をサードパーティーのアプリケーションプラットフォームに統合できます。通知のニーズに応じて、さまざまな通知チャネルの通知イベントを設定できます。通知チャネルには、Slack、Webhook、Jenkins、Email などが現在サポートされています。

通知をサードパーティーのアプリケーションプラットフォームに統合することで、プロジェクトメンバーが対応する通知イベントをトリガーした際に、通知がリアルタイムでサードパーティーアプリケーションプラットフォーム（例：Slack ボット）に送信されます。

「プロジェクト設定」->「通知設定」->「通知対象」->「新規」を通じて、新しい外部通知を作成できます。

詳細な手順については、こちらのリンクをご参照ください：

4. 実行環境管理

プロジェクトが作成された後、後続のインターフェース切り替えやデバッグ作業のために、プロジェクトの実行環境設定を適切に管理することが重要です。

プロジェクトは、進行中の異なる段階に応じて異なる実行環境にあることが多く、例えば開発環境、テスト環境、本番環境などが存在します。これらの環境はそれぞれ異なる**「プレフィックス URL」や「API パラメータ値」**に対応しています。プロジェクトの進行に伴い、環境が変更される場合、頻繁にインターフェースアドレスのプレフィックス URL を変更したり、パラメータを再設定したりするのは非常に面倒で、デバッグ作業に多大な負担をかけます。

Apidog では、正式環境、開発環境、テスト環境、ローカル Mock、クラウド Mock の 5 つの環境がデフォルトで提供されます。各環境には、サービス（プレフィックス URL）、環境変数、パラメータの 3 つの設定項目が含まれており、これらを基にして、自分のプロジェクト設定に置き換えることができます。

5. 変数管理

プロジェクトの実行環境設定を維持した後、プロジェクトの基本情報設定（例：トークン、テストユーザーのアカウントやパスワードなど）を維持する必要があります。このとき、Apidog の変数管理機能が役立ちます。

プログラミング言語と似ていて、Apidog の変数は複数の環境で再利用可能な値を扱うことができます。異なるインターフェースのテストケース（リクエストパラメータやスクリプトなど）と環境は、同じ変数を繰り返し参照できます。開発者は変数の値を一度変更するだけで、その変数を参照しているすべての値が一括で更新されるため、作業効率を大幅に向上させることができます。

Apidog には、次の 3 種類の変数があります：

• 環境変数
• グローバル変数
• 一時変数

環境変数
環境変数は最も一般的に使用される変数タイプです。同じ変数は異なる環境で異なる値を設定することができ、変数の値は環境の切り替えに応じて変更されます。このタイプの変数を使用して、異なる環境でのテストユーザー情報を管理できます。

グローバル変数
グローバル変数の値は、環境の切り替えによって変更されません。環境管理ページの左上で設定できます。ここでは、全体的に共通する設定情報やデータを管理し、統一的に運用することができます。

一時変数
一時変数は、単一のAPIテストケースやテスト管理内のテストケース、テストスイート実行中のみ有効で、システムに永続的に保存されることはありません。簡単に言えば、必要な場所で定義され、使用後は消失するものです。

6. パラメータ管理

Apidogでは、APIリクエストのパラメータを効率的に管理できます。パラメータの追加、編集、削除は非常に簡単で、特定のパラメータセットを再利用することが可能です。

よく使うパラメータ

よく使うパラメータを定義しておくと、APIテストを繰り返し実行する際に便利です。

グローバルパラメータ

グローバルパラメータは、全てのAPIリクエストに共通する設定を一度だけ行うことができ、プロジェクト全体で再利用が可能です。

注意： 実際のアプリケーションシナリオでは、ログイン認証のフィールドの値は、ログインインターフェースを通じて動的に設定されるもので、固定値ではありません。これはインターフェースで値を渡すことに関わる問題です。この場合、変数{{token}}タグを使って動的に値を設定する必要があります。今回は基本的なチュートリアルなので、ここでは深く掘り下げません。興味がある方は、ぜひ自分で研究してみてください。

7. データモデル管理

基本設定

データモデルはデータ構造から切り離せませんが、データ構造はデータフィールドから切り離せず、データフィールドはデータ型から切り離せません。インターフェースのデータ構造を管理するためには、Apidogのデータモデル機能を使用する必要があります。

Apidogのデータモデルは、主に「再利用性」に焦点を当てています。実際のプロジェクト開発において、1つの機能モジュール内の異なるエントポイントのデータ構造は、非常に似ていることが多いです。データモデルを維持してエントポイントでデータモデルを引用することで、同じフィールドのデータ型を変更する場合、各APIエントポイントで一つ一つ修正する必要はなく、該当するデータモデル内で変更するだけで済みます。

すでに作成したいデータ構造のJSONメッセージやXML形式のデータがある場合は、「JSONなどから生成」の方法を使って、データモデルを迅速に生成できます。

注意点として、実際の使用に応じて適切な上書きモードを選択する必要があります。完全上書きモードでは、すでに作成されたフィールドが上書きされるので注意してください。

高度な設定

フィールドを作成し、データ型を選択する際に、選べるデータ型があまり要望に合わないことがあります。たとえば、floatやlongなどの一般的なデータ型が選べないことがあります。

実際には、Apidogではデータ型が分類されており、各カテゴリ内にさらに細分化されたデータ形式があります。例えば、moneyというフィールドを管理する場合、データ型をFloatに設定したい場合、以下のように設定します。

データ型を「number」に設定すると、floatやdoubleなど、選択可能な型が表示されます。

もしApidogの既存のデータ形式では実際のAPIのデータ型に対応できない場合、公式では直接JSON Schemaを編集してデータ構造を定義する方法を推奨しています。Apidogのデータ構造とデータモデルは、完全にJSON Schemaの仕様に準拠しています。

8. コンポーネントライブラリ管理

Apidogでは、よく使うAPIレスポンスやリクエストのパターンをコンポーネントライブラリに保存しておくことで、再利用性が高まり、開発が効率化されます。

デフォルトレスポンステンプレート

プロジェクト内でAPIの返却データ構造が単一である場合、Apidogのデフォルトレスポンステンプレートを使用して管理できます。これにより、新しく作成したAPIは、すべてこのテンプレートをデフォルトで参照するようになり、便利で効率的です。以下の点に注意してください：

• 1.新しいAPIを作成する際、このテンプレートの内容が初期のレスポンスとして使用されます
• 2.デフォルトレスポンステンプレートを変更しても、既存のAPIには影響を与えず、今後作成されるAPIにのみ影響します
• 3.デフォルトレスポンステンプレートは一つだけで、追加や削除はできません

レスポンスコンポーネント

通常、標準的なシステム設計では、統一されたAPIレスポンスデータ形式を使用し、ステータスコードで異なる結果を区別します。そのため、統一されたAPIレスポンスデータ形式を管理するためには、Apidogのコンポーネントライブラリ機能を使用する必要があります。

プロジェクト内でよく使用するレスポンス結果データ形式（例えば404、500、200など）をここで管理します。APIドキュメントを作成する際、実際のAPIレスポンスに応じて異なるレスポンス結果テンプレートを引用することができます。これにより、フロントエンドの担当者は、異常なレスポンスデータ構造に基づいて適切なエラーハンドリングを行うことができます。

9. API作成

Apidogでは、APIを簡単に作成できます。手動での作成や、外部のAPI定義をインポートすることも可能です。

手動作成

• 1.ディレクトリの作成
  APIを作成する前に、まずはディレクトリ構造を設定し、APIの分類と検索を便利にします。選択したディレクトリ内でAPIを作成するか、既存のAPIをコピーして新しいAPIを作成することもできます。
  

• 2.グローバルパラメータとデフォルトレスポンステンプレートの自動引用
  新しいAPIは、自動的にグローバルパラメータとデフォルトレスポンステンプレートを引用し、手動で設定する時間を節約します。

• 3.APIドキュメントの設計
  API作成時には、以下の要素を含むドキュメントを作成することが重要です：

• APIパス：APIのアクセスパスを設定します
  

• リクエスト方法：GET、POSTなどのリクエスト方法を選択します

• リクエストパラメータ：実際のAPIに合わせてリクエストパラメータを入力します

リクエストパラメータは次の3種類に分けられます：
Queryパラメータ：通常、フィルター条件、ソート方法、ページネーションなどのオプションパラメータを渡すために使用されます。
Pathパラメータ：APIリクエストのパスにおける特定のリソースを指示するために使用されます。

Bodyパラメータ：HTTPリクエストボディ内で送信されるデータ（フォームデータ、JSONデータ、バイナリデータなど）を含みます。

既存のパラメータやデータモデルを引用することもできます。

• 4.レスポンス例の提供
  API設計が完了した後、レスポンスの例を提供し、対接チームがデータ構造を直感的に確認できるようにします。

• Mockデータ：Apidogは生成戦略タグを提供しており、このタグを使って異なるタイプのモックデータを簡単に生成できます。これにより、レスポンスデータをシミュレートする際に便利です

• 5.オンラインドキュメントの生成
  設計が完了したら、保存ボタンをクリックしてオンラインドキュメントを生成し、チームメンバーがアクセスできるようにします。

外部APIのインポート

外部から提供されたAPI仕様書（Swagger、Postmanなど）をApidogにインポートすることで、素早くAPIを作成できます。

ここではSwaggerの外部APIインポートの流れを例として説明します（インポートの権限が必要です）。事前にインポートするSwagger APIのドキュメント（Swagger公式URLを例に）を準備します。

ドキュメントURLをApidogのインポートエリアに貼り付けると、以下のような効果が得られます：

インポートしたいAPIやデータモデルを手動で選択できます。以下の2点に注意が必要です：

• SwaggerのAPIドキュメントはモジュールごとにエクスポートすることができず、すべてのAPIを一度にエクスポートする必要があります。これは、エクスポート方法を見つけられなかった可能性もあります

• 手動でインポートしたいAPIを選択するとき、APIとデータモデルをリンクさせることができず、APIがインポートされたのに対応するデータモデルが欠けている場合があります

インポート結果を見ると、かなり便利です。インポートされたAPIは、自動的に対応するデータモデルを参照しているので、非常に便利ですね！

10. 実行

Apidogでは、定義したAPIのリクエストを実行し、レスポンスを確認することができます。環境ごとに異なる設定を使用することで、APIの動作を確認できます。

実行環境

複数の実行環境（開発、テスト、本番、Mockなど）を設定し、それぞれに対して適切なリクエストを実行できます。

保存用例

実行したAPIのリクエストとレスポンスを保存し、後で再利用することができます。

履歴

過去に実行したリクエスト履歴を確認し、必要に応じて再実行することができます。

11. ドキュメントの共有

ここで、ApidogのAPIドキュメントのメンテナンス作業はほぼ完了です。バックエンドのメンバーがAPIを作成し終えたら、フロントエンドのメンバーにドキュメントを送る準備が整ったことになります。社内のメンバーにシンプルに共有する場合は、チームにメンバーを追加して、異なるプロジェクト権限を付与するだけで済みますが、外部のメンバーにドキュメントを共有する場合は、そう簡単にはいきません。そのため、このシナリオではApidogの「ドキュメント共有」機能を使うことになります。

APIドキュメントの共有範囲、セキュリティ、実行環境に基づいてカスタマイズして共有することができます。なんと素晴らしい！異なる役割の連携担当者や、異なるプラットフォームの担当者に対して、モジュールごとに異なるAPIドキュメントを共有することができ、非常に便利です。

結論

Apidogは、API設計からテスト、ドキュメンテーション、共有に至るまでのすべてのプロセスを統合的に管理できる強力なツールです。これらの機能を駆使することで、開発チームの作業効率が大幅に向上し、プロジェクトの進行がスムーズになります。今すぐApidogを活用して、API管理の新しいスタンダードを体験してみましょう！
(もっと詳しく知りたい方は、公式のヘルプドキュメントをご覧ください。)

最後まで読んでくださり、ありがとうございました！
この記事を読んで少しでも理解を深めていただければ幸いです！