Apidogプロジェクトでは、エンドポイントはModule → Folder → Endpointsという階層構造で管理されます。
- モジュールは独立したOpenAPIファイルを表し、通常はビジネスドメインまたはサービスごとにグループ化されます。
- フォルダーは、モジュール内で機能または関数ごとにエンドポイントを整理します。
- エンドポイントは、実際のOpenAPI仕様またはAPI定義です。
この構造を理解することが、APIを効率的に整理するための鍵となります。
以下に簡単な階層の例を示します。
Apidog Project (Apidogプロジェクト)
│
├── Module: User Service (ユーザーサービス) (ビジネスドメインまたはサービスで分割)
│ │
│ ├── Folder: User Authentication (ユーザー認証) (機能カテゴリ)
│ │ │
│ │ ├── Endpoint: POST /login (ログイン)
│ │ └── Endpoint: POST /register (登録)
│ │
│ └── Folder: User Info (ユーザー情報)
│ │
│ └── Endpoint: GET /users/{id} (ユーザー情報取得)
│
└── Module: Order Service (注文サービス)
│
├── Folder: Order Management (注文管理)
│ │
│ ├── Endpoint: POST /orders (注文作成)
│ └── Endpoint: GET /orders/{id} (注文詳細取得)
│
└── Folder: Payment (支払い)
│
└── Endpoint: POST /payment/submit (支払い送信)Apidogにおけるモジュールの理解
プロジェクトの階層を理解した後、次の疑問は「すべてのプロジェクトにモジュールが必要なのか？」「いつ新しいモジュールを作成すべきか？」です。
新しいプロジェクトを作成すると、Apidogは自動的にデフォルトモジュールを生成します。プロジェクトが単一のバックエンドサービスまたは少数のエンドポイントしか含まない場合、このデフォルトモジュールで通常は十分です。しかし、複数の異なるAPIサービスを管理する必要がある場合は、それぞれに個別のモジュールを作成できます。
例えば、プロジェクトのバックエンドには、User（ユーザー）、Product（製品）、Order（注文）、Logistics（物流）のようなサービスが含まれる場合があります。これらはそれぞれ特定のドメインを担当し、異なるサービスURLにデプロイされることがよくあります。この場合、これらのサービスごとに個別のモジュールを作成し、エンドポイントを独立して管理することをお勧めします。
フォルダーツリーの上にある+ボタンをクリックし、Moduleを選択することでモジュールを作成できます。
作成されると、左側のプロジェクトツリーに他のモジュールと並んで表示され、フォルダーとエンドポイントのための独自のスペースが確保されます。各モジュール内でエンドポイントやフォルダーを自由に追加できます。
モジュールは互いに独立しており、それぞれ独自のエンドポイント、スキーマ、コンポーネント、モジュール変数を持っています。ただし、スキーマはモジュール間で参照できます。さらに、環境変数、データベース接続、共通スクリプトなどのプロジェクトレベルの設定は、すべてのモジュールからアクセス可能です。
各モジュールは完全なOpenAPI仕様ファイルに対応しています。プロジェクトをエクスポートする際、OpenAPIファイルはモジュールごとに生成されます。
モジュール内のフォルダーの理解
モジュールを作成した後、次のステップは、その中にエンドポイントをどのように構造化するかを計画することです。
すべてのモジュールは、すべてのサブフォルダーとエンドポイントを保持するルートフォルダーから始まります。
ルート直下にフォルダーを作成することも、既存の他のフォルダー内にネストすることもできます。
フォルダー構造を設計する際には、モジュールの複雑さを考慮してください。エンドポイントが少ないモジュールの場合、機能別に整理されたシンプルな単一レベルのフォルダーで通常は十分です。しかし、より複雑なモジュールの場合、すべてを整理し、ナビゲートしやすくするために、適切に構造化された多層フォルダーを作成する方が良いでしょう。
例えば、ユーザーサービスモジュールでは、次のようなトップレベルのフォルダーを持つことができます。
- ユーザー認証（ログイン、登録、パスワードリセットのエンドポイント用）
- ユーザー情報
- アクセス制御
あるフォルダーが大きくなりすぎたり、論理的に独立している場合、それをスタンドアロンモジュールに変換できます。
フォルダー名の横にある...アイコンをクリックし、...More > Convert to a new Moduleを選択します。これにより、プロジェクト構造を拡張時に適切に整理し続けることができます。
モジュールの環境管理と設定
構造化されたエンドポイントに加えて、各モジュールは通常、異なるサービスアドレスまたはデプロイ環境に対応しています。これらは環境管理で簡単に設定できます。
環境管理設定では、各モジュールのベースURLを個別に設定できます。例えば、テスト環境では次のようになります。
- ユーザーサービス →
http://user-service:8001 - 注文サービス →
http://order-service:8002
環境を切り替えると、Apidogは各モジュールのベースURLを自動的に更新します。例えば、開発環境からテスト環境に切り替える際、ユーザーサービスモジュールのベースURLはhttp://localhost:8001からhttp://user-service:8001に、注文サービスモジュールのベースURLはhttp://localhost:8002からhttp://order-service:8002に変更されます。
環境変数はすべてのモジュールで共有され、環境間で異なる設定を保存するのに最適です。対照的に、モジュール変数は各モジュール固有のものであり（例えば、独自のAPIキーやトークンなど）、そのモジュール内の任意のエンドポイントで使用できます。
スキーマの管理と再利用
効率的なスキーマ管理は、重複を避け、モジュール間の一貫性を確保するのに役立ちます。
各モジュールには独自のスキーマ管理セクションがあり、ビジネス関連のデータ構造を定義および維持できます。これらのスキーマは、モジュール内で再利用したり、他のモジュールから参照したりできます。
例えば、ユーザーサービスモジュールはユーザー関連のスキーマを定義します。注文サービスモジュールは注文関連のスキーマを定義します。注文サービスがユーザー情報を参照する必要がある場合、ユーザーサービスのスキーマを単に再利用でき、再作成する必要はありません。
PostmanからApidogへ：インポートされたコレクションとエンドポイントの整理
チームが以前Postmanを使用していた場合、既存のコレクションとエンドポイントを簡単にApidogに移行できます。
インポート中：
- 各Postmanコレクションはモジュールになります。
- フォルダー構造は自動的にマッピングされます。
- エンドポイントとスキーマは保持されます。
これにより、Apidogのモジュールシステムを活用しながら、慣れ親しんだAPI構造を維持できます。
結論
明確なモジュールを定義し、フォルダーを整理し、スキーマを再利用することで、Apidogプロジェクトをクリーンでスケーラブル、かつ共同作業しやすい状態に保つことができます。
Apidogのモジュール設計は、チームがより迅速に作業し、混乱を避け、設計からドキュメント作成、テストに至るまで、複雑なAPIをより効率的に管理するのに役立ちます。