既存のSwagger APIドキュメントをApiDogに移行する方法
Swagger によって管理される API を Apidog に移行するには、いくつかの方法があります。このガイドでは、Swagger ファイルをエクスポートして Apidog にインポートするための 4 つの簡単な方法を示します。これには、スケジュールされたインポート用のオンラインリンクを利用する方法、ワンクリックでアップロードするための IDEA プラグインの利用、および Open API を通じたインポートが含まれます。以下に各方法の詳細な手順を示します。
方法 1: Swagger ファイルをエクスポートして Apidog にインポートする
これは、最も単純なアプローチであり、一度きりの移行に適しています。特に API ドキュメントが安定している場合に最適です。具体的な手順は以下の通りです。
ステップ 1. Swagger ファイルをエクスポート
Swagger UI で、API ドキュメントを .yaml または .json ファイルとしてエクスポートします。通常、Swagger UI の左上隅にファイルをダウンロードするオプションがあります。
インターフェースに URL リンクが表示されない場合は、「F12」または「Ctrl+Shift+I」を押してブラウザのコンソールを開き、「Network」 -> 「Fetch/XHR」に移動してページをリフレッシュします。これにより、新しいウィンドウで開いてダウンロードできる .json ファイルが表示されるはずです。
ステップ 2. Swagger ドキュメントを Apidog にインポートする
Apidog を開き、プロジェクトに移動し、プロジェクト設定 -> データのインポート -> OpenAPI/Swagger を選択します。以前にエクスポートした .yaml または .json ファイルをアップロードします。公開アクセス可能なソースファイルの URL がある場合は、URL 経由でもインポートできます。
アップロードが完了したら、Apidog は自動的に API ドキュメントを解析してインポートし、プレビューインターフェースでさらに編集・管理できます。
方法 2: オンラインリンク経由でのスケジュールインポート
Swagger API ドキュメントが頻繁に更新される場合、手動でのエクスポートとインポートは煩雑になる可能性があります。この場合、Apidog のスケジュールインポート機能を利用して、オンラインの Swagger ドキュメントを自動的に同期できます。手順は以下の通りです。
ステップ 1. オンラインリンクを取得
Swagger ドキュメントに公開 URL でアクセスできることを確認します。
https://petstore.swagger.io/v2/swagger.jsonステップ 2. OpenAPI ドキュメントをインポートするためのスケジュールされたタスクを設定
Apidog で、スケジュールインポートを設定したいプロジェクトに移動し、プロジェクト設定 -> データのインポート -> スケジュールインポートを選択して新しいタスクを作成します。オンライン Swagger ドキュメントの URL（データソース URL）を入力し、インポート間隔（例: 3 時間ごと、12 時間ごとなど）を設定します。
保存後、Apidog は指定された間隔に基づいて最新の API ドキュメントを自動的に取得して更新します。
方法 3: IDEA プラグインを経由したワンクリックアップロード
Apidog IDEA プラグインは、ローカルの Java および Kotlin プロジェクトのソースコードを認識し、自動的に API ドキュメントを生成して Apidog プロジェクトに同期します。Spring Boot などの一般的なフレームワークをサポートしており、全く侵入のないコード体験を提供します。
移行プロセスをより効率的にするために、IDEA プラグインを使用するための手順は以下の通りです。
ステップ 1. Apidog IDEA プラグインをインストール
IntelliJ IDEA（2019.3 以降のバージョン）を開き、設定 -> プラグインに移動し、「Apidog Helper」を検索してインストールします。インストール後に IDEA を再起動します。
ステップ 2. API アクセストークンを設定
Apidog で、右上隅のプロフィール画像をクリックし、アカウント設定 -> API アクセストークンを選択します。ここでAPIアクセストークンを生成し、必要に応じて有効期限を設定します。
IDEA で、「Apidog Helper」プラグインの設定を開き、API アクセストークンを入力して「テストトークン」をクリックします。成功した場合は、「適用」または「OK」をクリックして設定を保存します。
ステップ 3. API を同期
プロジェクトディレクトリツリー内のモジュールノードを右クリックし、「Apidog にアップロード」を選択してモジュール内のすべてのインターフェースを同期します。あるいは、Controller ファイルを開き、右クリックして「Apidog にアップロード」を選択することで、Controller 内のすべてのインターフェースを同期できます。
最初の同期時には、関連するチームとプロジェクトを選択するよう促す設定ダイアログが表示され、インターフェースはデフォルトでプロジェクトのルートディレクトリにアップロードされます。
ステップ 4. API ドキュメントを表示
同期が成功すると、Apidog を開いて自動生成された API ドキュメントを表示します。
方法 4: Open API 経由でインポート
Apidog では、API 開発者が API データを Swagger/OpenAPI 形式で直接インポートできるオープン API を提供しており、オープン API ドキュメントは https://openapi.apidog.io/ で入手可能です。
Open API 経由でのインポート手順は以下の通りです。
ステップ 1. API アクセストークンを取得
Apidog で、右上隅のプロフィール画像をクリックし、アカウント設定 -> API アクセストークンを選択して、認証用の API アクセストークン（access_token）を生成します。トークンの有効期限は必要に応じて調整します。
ステップ 2. プロジェクト ID を取得
Apidog で、プロジェクト設定 -> 基本設定に移動してプロジェクト ID を確認します。プロジェクト ID は各プロジェクトの一意の識別子であり、データを正しいプロジェクトにインポートするために API を呼び出す際に必要です。
ステップ 3. オープン API を呼び出す
OpenAPI/Swagger 形式のデータを Apidog にインポートするには、次のエンドポイントを呼び出すことができます: https://api.apidog.com
パスパラメータ
| パラメータ名 | パラメータタイプ | 必要 | 説明 |
|---|---|---|---|
| projectId | String | 必要 | プロジェクト ID、データをインポートするターゲットプロジェクトを指定するために使用されます。 |
| 例: | https://api.apidog.com/v1/projects/3760990/import-openapi |
ボディパラメータ
| パラメータ名 | パラメータタイプ | 必要 | 説明 |
|---|---|---|---|
| input | String/Object | 必要 | インポートする OpenAPI/Swagger データで、JSON/YAML の文字列またはオブジェクトにラップされた URL であることができます。 |
| options | Object | オプション | ターゲットディレクトリ ID の設定、インポートインターフェースの上書き動作などのための高度なオプション。関係するパラメータの詳細は Apidog オープン API ドキュメントで確認できます。 |
リクエストボディの例:
{
"input": {
"url": "https://petstore.swagger.io/v2/swagger.json"
},
"options": {
"endpointOverwriteBehavior": "CREATE_NEW",
"endpointCaseOverwriteBehavior": "CREATE_NEW",
"updateFolderOfChangedEndpoint": false
}
}
inputOpenAPI データ文字列を直接提供する場合、次の形式で渡すことができます。文字列は JSON、YAML、または X-YAML 形式にすることができます:
{
"input": "{'openapi':'3.0.0','info':{'title':'Sample API','version':'1.0.0'},'paths':{'/sample':{'get':{'summary':'Sample endpoint','responses':{'200':{'description':'successful operation'}}}}}}"
}
OpenAPI/Swagger 形式のデータを指す公開アクセス可能な URL を提供する場合、次の形式で渡すことができます:
{
"input": {
"url": "https://petstore.swagger.io/v2/swagger.json"
}
}
データソースが認証を必要とする場合、認証のための Basic Auth 情報も提供できます:
{
"input": {
"url": "https://petstore.swagger.io/v2/swagger.json",
"basicAuth": {
"username": "apiUser",
"password": "securePassword123"
}
}
}
ヘッダー パラメータ
上記の必要なパラメータに加えて、関係する認証情報をリクエストヘッダーにも含める必要があります。以下の通りです:
| パラメータ名 | パラメータタイプ | 必要 | 説明 |
|---|---|---|---|
| X-Apidog-Api-Version | String | 必要 | オープン API バージョン番号; 現在サポートされているバージョンは 2024-03-28 です。 |
| Authorization | String | 必要 | 認証形式; Bearer の後にステップ 1 で取得した個人アクセストークンを続けるべき。 |
例:
'X-Apidog-Api-Version': '2024-03-28'
'Authorization': 'Bearer APS-OVWel6j5103zaaaaaaQle99fGNBw8ucH'
レスポンスの例
API 呼び出しが成功すると、次のような JSON レスポンスが返され、インポートプロセスの統計（作成された、更新された、および無視されたインターフェースの数や、作成されたおよび更新されたデータモデルの数）が含まれます。エラーメッセージが返された場合、必要なパラメータが欠落しているか、インポートされたデータ形式が正しいかを注意深く確認してください。
{
"data": {
"counters": {
"endpointCreated": 20,
"endpointUpdated": 0,
"endpointIgnored": 0,
"endpointFailed": 0,
"endpointFolderCreated": 3,
"endpointFolderUpdated": 0,
"endpointFolderIgnored": 0,
"endpointFolderFailed": 0,
"schemaCreated": 0,
"schemaUpdated": 7,
"schemaIgnored": 0,
"schemaFailed": 0,
"schemaFolderCreated": 0,
"schemaFolderUpdated": 0,
"schemaFolderIgnored": 0,
"schemaFolderFailed": 0
}
}
}ステップ 5. インポート結果を表示
インポートが完了したら、該当する Apidog プロジェクトで生成された API ドキュメントを表示できます。入力パラメータやレスポンスメッセージの詳細に関しては、Apidog オープン API ドキュメントを参照してください。
よくある質問
- ファイルインポート中にエラーが発生した場合はどうすればよいですか?
.yamlファイルをインポートする際に解析エラーが発生した場合、これはファイルが OpenAPI の仕様に準拠していないことを示し、修正が必要です。エラーを診断するためにファイルを Swagger Editor にアップロードできます。問題を解決した後、再度インポートを試みてください。
結論
上記の 4 つの方法を使用することで、Swagger 管理の API を Apidog に簡単に移行できます。各方法は異なるシナリオに適しており、ニーズに基づいて最も適切な方法を選択できます。手動インポート、スケジュールされたオンライン同期、プラグインアップロード、またはオープン API 統合を通じて、Apidog は効率的で便利な API 管理体験を提供します。