apidog-import-export

インポート、エクスポート、品質ゲート

前提条件：まず ../apidog-cli/SKILL.md を読んでください。安定版のエントリースキルとこのドメインスキルが矛盾する場合は、最新の CLI ヘルプとこのスキルを正としてください。

正確な引数を確認するには、必ず最新の CLI ヘルプを使用してください。インポート前に、ファイル形式、OpenAPI の品質ゲート、ルートスケルトンのリスク、タグによるグループ化、ネイティブ形式のモジュール戦略、ignoreCount、クリーンな検証プロジェクトが必要かどうかを確認してください。インポート後、エージェントは agentHints、list/get、関連する場合は run/report で結果を検証する必要があります。インポートコマンドが成功を返しただけで完了とみなさないでください。

使用する場面

• コード、PRD、要件文書、テスト文書、ディスカッションから API 仕様を生成し、Apidog にインポートする場合。
• OpenAPI、Postman、HAR、Apidog ネイティブ形式、その他のプロジェクトデータをインポートする場合。
• 自動インポートを設定する場合。
• OpenAPI、Markdown、HTML、Postman、Apidog ネイティブ形式をエクスポートする場合。
• 生成された仕様がルートスケルトンにすぎないかどうかを判断する場合。
• Apidog プロジェクトを移行、バックアップ、コピーする場合。特に、モジュールの再利用や新規作成を制御する必要がある場合。

使用しない場面

• 既存のエンドポイント、テストケース、シナリオステップをテストシナリオにインポートまたはコピーする場合：test-scenario import-steps または test-scenario add-ref を使用する apidog-test-scenario を使用してください。
• シナリオのステップ、変数、アサーション、プロセッサーを厳密に管理する場合：apidog-test-scenario を使用してください。

コマンドのエントリーポイント

import、import auto-import、export、export settings には最新の CLI ヘルプを使用してください。インポート前に、以下の品質ゲートを必ず確認してください。

基本原則

1. 抽出スクリプトを書く前に、プロジェクト内に既存のジェネレーターがないか検索します。
2. パスがすべてそろっていても、API 仕様が完全とは限りません。
3. インポート前に品質指標を出力します。
4. 完全性と読みやすさの両方を検証します。
5. インポート戦略が不確かな場合は、既存プロジェクトを汚染するのではなく、一時プロジェクトまたは修正版プロジェクトで先に検証します。
6. インポート結果で ignoreCount の値が大きい場合は、通常の成功ではなくリスクの兆候です。
7. OpenAPI の Apidog フォルダーのグループ化は、operation タグに依存します。
8. ファイル拡張子が実際の形式と一致するとは限りません。

標準的な手順

ステップ 0. タスクの種類を特定する

まず、ユーザーが求めているタスクの種類を判断します。

タスク	次のステップ
コード、PRD、ドキュメントから仕様を生成してインポートする	ステップ 1 に進む
既存ファイルを直接インポートする	ステップ 3 から始める
自動インポートを設定する	最新の CLI ヘルプとスキーマを読み、設定を作成する
ドキュメントまたは OpenAPI をエクスポートする	export を直接使用し、ファイルが生成されたことを確認する
Apidog プロジェクトを移行またはバックアップする	Apidog ネイティブ形式でエクスポート／インポートし、モジュールのインポート戦略を確認する
既存のリソースをテストシナリオにインポートする	apidog-test-scenario に切り替える。OpenAPI インポートは使用しない

ユーザーが対象プロジェクト、チーム、インポート戦略、新規プロジェクトの作成可否を指定していない場合、安全であれば文脈から判断します。不確かな場合は、必要最小限の質問を 1 つだけします。

ステップ 1. 既存のジェネレーターを検索する

ソースコード、ドキュメント、PRD、テストから API 仕様、ドキュメント、型を生成する依頼では、まずプロジェクト内に既存のジェネレーターがないか検索します。

openapi
swagger
routegen
route-gen
docs generator
api docs
schema generator
cmd/openapi
cmd/*openapi*

適切な進め方：

• まずプロジェクト独自のジェネレーターを実行します。
• ハンドラーのリクエスト／レスポンス構造体、DTO、スキーマを抽出するツールを優先します。
• ルーターファイルを手作業で解析することから始めないでください。多くの場合、メソッドとパスだけのスケルトンになります。

ジェネレーターが見つからない場合は、フレームワークのルート、コメント、DTO、スキーマ、テスト、ドキュメントからの生成を検討します。その場合もステップ 3 以降の品質ゲートを続けて実施してください。

Step 2. 仕様を生成して形式を確認する

• プロジェクトジェネレーターまたは公式コマンドを実行します。
• 元の成果物を保存し、ユーザー所有のファイルを直接上書きしないでください。
• 拡張子で形式を判断しないでください。
• 生成ファイルを読み込む前に、先頭部分を確認するか、JSON／YAML 対応ツールで解析します。
• ジェネレーターが .json ファイルに YAML を書き込む場合があります。その場合は .yaml に名前を変更するか、YAML として解析してください。

Step 3. インポート前の指標を収集する

インポート前に、生成された OpenAPI ファイルを解析して実際の指標を報告します。サンプル値、既定値、プレースホルダー値は使用しないでください。

必須の指標：

指標	意味	目的
paths	OpenAPI パスの数	API 規模の推定
operations	実際のオペレーション数	インポート規模の推定
schemas	components.schemas の数	モデルの網羅性の推定
writes	POST／PUT／PATCH などの書き込み API	リクエストボディの網羅性の目標
withBody	requestBody を持つ書き込み API	リクエストボディの網羅性
emptyObjectBodies	リクエストボディのスキーマが空のオブジェクト	ルートスケルトンのリスク

現在のファイルから得られた実際の統計を、表または JSON で出力します。すべての値はファイルの解析結果に基づく必要があります。

Step 4. 仕様の完全性を判断する

• スキーマ数を固定の品質基準として使用しないでください。
• 小規模なプロジェクト、GET 専用プロジェクト、ヘルスチェック、Webhook パススルー、または JSON 以外のボディを使うプロジェクトでは、schemas=0/1 でも問題ない場合があります。
• API や書き込みオペレーションが多い大規模なプロジェクトで、スキーマが非常に少ない場合は、ルートスケルトンである可能性が高いです。
• 多くの POST／PUT／PATCH リクエストボディが欠落している、または {} で表されている場合は、重大なリスクの兆候です。
• メソッドとパスだけでは、requestBody、レスポンス、スキーマの完全性は証明できません。

リスクの兆候：

• オペレーションは多いものの、スキーマがほとんどない。
• 書き込み API に requestBody がない。
• リクエストボディが空のオブジェクトになっている。
• レスポンスが汎用文字列または空のオブジェクトのみである。
• タグが欠落している、または汎用的すぎるため、フォルダーのグループ分けが適切でない。

リスクが高い場合は、そのリスクを説明し、インポート前にジェネレーター／ソースのアノテーションを改善するか、一時プロジェクトにインポートして視覚的に検証することを推奨します。

Step 5. インポートする

形式と引数の正確な内容は、最新の CLI ヘルプを参照してください。コマンドの形式の例：

apidog import --project <projectId> --format openapi --file <openapiFile>
apidog import --project <projectId> --format postman --file <postmanFile>
apidog import --project <projectId> --format apidog --file <nativeFile> --module-import-mode match-name

Apidog のネイティブプロジェクトファイルの場合は、モジュールの扱いを慎重に選択してください。

• 既定の match-name では、ソースモジュール名がターゲットモジュール 1 つと一意に一致する場合に限り、そのターゲットモジュールを再利用します。一致しない場合は新しいモジュールを作成します。
• new では、--module-map の対象になっていないソースモジュールに対して、新しいモジュールを作成します。
• --module-map では、ソースモジュールをターゲットモジュール ID、default、または new に明示的にマッピングします。

同名による曖昧さを避けるため、--module-map ではターゲットモジュール ID を指定してください。

Step 6. インポート結果を確認する

インポート後は、成功フラグだけでなく、次の点も確認してください。

• success と終了コードを確認します。
• インポート件数、無視された件数、警告を確認します。
• endpoint list、schema list、フォルダー／モジュールのビュー、または関連コマンドを使って、リソースが表示されることを確認します。
• API が想定したモジュール／フォルダーに配置されたことを確認します。
• テストリソースをインポートする場合は、それぞれのドメインコマンドでテストケース、シナリオ、スイート、カテゴリーを確認します。
• クライアント上の表示が重要な場合は、同じプロジェクト／ブランチ／モジュール／カテゴリーのコンテキストを開くか、CLI で読み戻して正確な配置を確認します。

ignoreCount が多い場合やリソースが見つからない場合は、同じインポートを何も考えずに繰り返さないでください。まず形式、モジュール戦略、未対応のリソースタイプ、警告の詳細を調査します。

エクスポートのルール

対応形式とオプションについては、最新の CLI ヘルプを参照してください。エクスポート後は、次の点を確認します。

• 出力ファイルが存在することを確認します。
• 想定どおりの有効な JSON／YAML／Markdown／HTML かを確認します。
• OpenAPI エクスポートでは、拡張プロパティが必要かどうかを確認します。
• ネイティブエクスポートは移行／バックアップに使用し、明示的なインポート戦略と組み合わせます。

コマンドの形式の例：

apidog export --project <projectId> --format openapi --output <file>
apidog export --project <projectId> --format markdown --output <file>
apidog export --project <projectId> --format apidog --output <file>

よくある復旧方法

症状	対処方法
インポートには成功するが、API が見つからない	警告、ignoreCount、モジュール戦略、list/get の結果を確認してください
API のグループ分けが適切でない	OpenAPI のオペレーションタグを確認してください
生成された仕様にパスしか含まれていない	より適切なジェネレーターを探すか、DTO／スキーマの抽出を強化してください
ネイティブインポートでモジュールが重複して作成される	--module-map または --module-import-mode match-name を慎重に使用してください
エクスポートファイルが使用できない	形式、出力先、ファイルが想定どおり JSON／YAML／HTML／Markdown かどうかを確認してください