yapi

YApi インターフェースドキュメント

インストール／更新

推奨するインストール／更新方法：

npx skills add leeguooooo/cross-request-master -y -g

スキルのインストール後に推奨する設定の初期化方法：

yapi config init --base-url=https://your-yapi-domain.com --auth-mode=global --email=YOUR_EMAIL
yapi login --base-url=https://your-yapi-domain.com --browser

~/.yapi/config.toml も同時に書き込みたい場合の互換性のある方法：

npm install -g @leeguoo/[email protected]
yapi install-skill --yapi-base-url=https://your-yapi-domain.com --yapi-auth-mode=global --yapi-email=YOUR_EMAIL --force

コマンドポリシー

常に実際の yapi CLI を直接使用してください。ユーザーのプロジェクトからプラグイン内の node scripts/... ファイルを呼び出してはいけません。Cursor または Claude Code 内では、コマンドはユーザーのワークスペースから実行されるため、相対パスで指定したプラグインのパスは信頼できません。

yapi コマンドを優先してください。見つからない場合は、グローバルインストールを強制せず、1 回限りの npx にフォールバックします。

yapi -h
# fallback:
npx -y -p @leeguoo/[email protected] yapi -h

以下のコマンド例では、yapi を npx -y -p @leeguoo/[email protected] yapi に置き換えられます。 CLI のバージョンがインストール済みのスキルのスナップショットより新しい場合、yapi は警告を表示し、再実行を求めます。

npx skills add leeguooooo/cross-request-master -y -g
# compatibility:
npx -y -p @leeguoo/[email protected] yapi install-skill --force

セットアップ／認証の初期化

1. ~/.yapi/config.toml がある場合は、設定済みの base_url を読み取ります。
2. 設定がない場合は、ブラウザーでのログインによる初期化を優先します。

yapi login --base-url https://your-yapi-domain.com --browser
# optional explicit page:
yapi login --base-url https://your-yapi-domain.com --login-url https://your-yapi-domain.com/

3. ユーザーがメールアドレス／パスワードを提供した場合は、グローバル認証も利用できます。

yapi login --base-url https://your-yapi-domain.com --email [email protected] --password '***'

4. 詳細な操作に進む前に、ログイン状態を確認します。

yapi whoami

クイックワークフロー

1. まずユーザー入力を分類してください — 種類がわかるまで、戦略を選ばないでください。
   • A. YApi ページの URL（https://yapi.example.com/project/123/api/456）→ パスから ID を抽出 → yapi interface get --id 456。検索は不要です。
   • B. HTTP エンドポイントのパス（/api/auth/token、/v1/users/:id）→ 以下の ## HTTP パスでインターフェースを検索する を参照してください。yapi search はパスをインデックス化していません。このケースでは使用しないでください。
   • C. 製品キーワード（语音房列表、voice room）→ キーワードを拡張して yapi search を実行します（## キーワードの拡張 を参照）。
   • D. 数値の api_id → 直接 yapi interface get --id <api_id> を実行します。
2. 認証を確認（yapi whoami）し、必要に応じて yapi login --browser を実行します（ベース URL を開き、ブラウザーでログインを完了してから、Enter キーを押して Cookie を同期します）。
3. まず生の JSON を取得してから要約します。対象はメソッド、パス、ヘッダー、パラメーター、本文、レスポンスのスキーマ／例です。
4. ドキュメントの同期タスクでは、まず --dry-run を実行してから、実際に同期します。
5. ドキュメントの同期で引き続き 413 が発生する場合、CLI はすでに --mermaid-classic を付けてファイルを再試行しています。それでも失敗する場合は、ドキュメントを分割するか、埋め込み図を減らします。

HTTP パスでインターフェースを検索する

ユーザーが /api/auth/token のような HTTP エンドポイントのパス（YApi ページの URL ではないもの）を指定した場合、YApi のプロジェクト検索はインターフェースのパスをインデックス化していないため、yapi search は空の結果を返します。代わりに、組み込みの --path フィルターを使って yapi interface list-menu を実行してください。フィルタリングは CLI が行うため、シェルのパイプは不要です。

必須入力：プロジェクト ID。ユーザーが指定していない場合は、まず尋ねるか、候補を一覧表示します（yapi project list --group-id <id>）。推測でプロジェクト／グループの列挙を始めないでください。

# substring match, case-insensitive (matches /api/auth/token, /api/auth/token/refresh, etc.)
yapi interface list-menu --project-id 365 --path /api/auth/token

# narrow further by HTTP method (case-insensitive exact match)
yapi interface list-menu --project-id 365 --path /api/auth/token --method POST

# combine to find all POST endpoints under a prefix
yapi interface list-menu --project-id 365 --path /api/auth --method POST

フィルタリング後のレスポンス形式：

{
  "errcode": 0,
  "data": {
    "matches": [
      { "project_id": 365, "catid": 100, "cat_name": "Auth",
        "_id": 31400, "title": "Get Token", "path": "/api/auth/token", "method": "POST" }
    ],
    "total": 1
  }
}

_id を特定したら、詳細を取得します。

yapi interface get --id 31400

アンチパターン — 以下は実行しないでください：

• ❌ yapi search --q '/api/auth/token'（プロジェクト検索はパスをインデックス化していないため、空の結果を返します）
• ❌ yapi interface list --project-id X --limit all | python ...（時間がかかり、壊れやすく、ほとんどのセキュリティゲートでブロックされます）
• ❌ グループ → プロジェクトを列挙し、パスがどこにあるか推測するために search を繰り返すこと。代わりに、ユーザーにプロジェクトを尋ねてください。

キーワードの拡張

yapi search が一度失敗しただけで検索を打ち切らないでください。

ユーザーが「语音房列表」「房间列表」「房间详情」「推荐房间」「语音房」「直播间」など、曖昧な製品用語で検索を依頼した場合：

1. まず元のフレーズで検索します。
2. 直接一致する結果がなければ、ユーザーに詳細を尋ねる前に、関連性の高い別の表現を3～6個使ってすぐに再検索します。
3. 中国語や英語の別表現、エンドポイント形式の名詞を優先します。
4. それでもインターフェースが見つからない場合は、諦める前に、関連しそうな名詞やカテゴリを個別に検索します。

ルーム形式のクエリでの展開例：

• 语音房列表
• 房间列表
• 语音房
• 房间详情
• 房间推荐
• room list
• room detail
• voice room

例：

yapi search --q "语音房列表"
yapi search --q "房间列表"
yapi search --q "语音房"
yapi search --q "房间详情"
yapi search --q "room list"
yapi search --q "voice room"

検索語を展開しても有用なインターフェースが見つからない場合に限り、ユーザーにプロジェクト名や追加のキーワードを尋ねてください。

URL の検出

1. ~/.yapi/config.toml から設定済みの base_url を読み取ります。

rg -n "^base_url\\s*=" ~/.yapi/config.toml

2. URL のオリジンが base_url と一致する場合、パスから ID を抽出します：
   • /project/123/... → project_id=123
   • .../api/456 → api_id=456
   • .../api/cat_789 → catid=789
3. api_id がある場合は、直接検索を優先します：

yapi --path /api/interface/get --query id=<api_id>

よく使うコマンド

# version/help
yapi --version
yapi self-update
yapi -h

# auth
yapi whoami
yapi login --base-url https://your-yapi-domain.com --browser
yapi login --browser
yapi login --login-url https://your-yapi-domain.com/
yapi logout

# search / fetch
yapi search --q keyword --project-id 310
yapi --path /api/interface/get --query id=123
yapi --path /api/interface/list_cat --query catid=123
yapi --path /api/interface/list_cat --query "catid=4631&limit=50&page=1"

# browse entities
yapi group list
yapi project list --group-id 129 --page 1 --limit 10
yapi project get --id 365
yapi project token --project-id 365
yapi interface list-menu --project-id 365
yapi interface list-menu --project-id 365 --path /api/auth/token
yapi interface list-menu --project-id 365 --path /api/auth --method POST
yapi interface list --project-id 365 --limit all
yapi interface get --id 31400
yapi interface cat add --project-id 365 --name "公共分类" --desc ""
yapi interface cat update --cat-id 3722 --name "公共分类 1" --desc "公共分类"
yapi interface cat delete --cat-id 4169
yapi env --project-id 365
yapi member list --project-id 365
yapi follow
yapi user search --q keyword
yapi log list --type group --type-id 129 --page 1 --limit 10

# exports / test collections
yapi export --project-id 365 --type swagger --name openapi.json
yapi col list --project-id 365
yapi col cases --id 12 --project-id 365

設定キャッシュの場所：

• 設定：~/.yapi/config.toml
• 認証キャッシュ：~/.yapi-mcp/auth-*.json

ブラウザログインの依存関係：

agent-browser-stealth -V
# install once if missing browser runtime
agent-browser-stealth install

ドキュメントの同期

バインドモード（推奨）：

yapi docs-sync bind add --name projectA --dir docs/release-notes --project-id 267 --catid 3667
yapi docs-sync bind list
yapi docs-sync bind get --name projectA
yapi docs-sync bind update --name projectA --source-file architecture.md
yapi docs-sync --binding projectA --dry-run
yapi docs-sync --binding projectA --source-file architecture.md
yapi docs-sync --binding projectA

注意事項：

• バインドファイル：.yapi/docs-sync.json
• マッピングの出力先：.yapi/docs-sync.links.json、.yapi/docs-sync.projects.json、.yapi/docs-sync.deployments.json
• バインドがグローバルな ~/.yapi/docs-sync.json にある場合、相対パスの --dir 値は現在の git プロジェクトのルートを基準に解決され、$HOME からの相対パスとして保存されます。
• デフォルトでは変更されたファイルのみを同期します。全ファイルを同期するには --force を使用してください。
• バインドがない場合は、ディレクトリ内の .yapi.json 設定をフォールバックとして使用できます。
• yapi docs-sync bind remove --name projectA はバインドを削除します。
• --source-file はバインドの source_files を上書きします。--clear-source-files はバインドの更新時に保存済みのリストを消去します。
• --dry-run はアップロード前に、Markdown／HTML／ペイロードのサイズを含むファイルごとのプレビュー行を表示します。
• アップロードで 413 Payload Too Large が発生した場合、CLI はまずそのファイルに --mermaid-classic を指定して再試行します。それでも失敗する場合は、ペイロードサイズ、解析されたサーバーの上限（取得可能な場合）、最大の Mermaid ブロックを報告します。
• Mermaid／PlantUML／Graphviz／D2 のレンダリングには、ローカルでのツールの利用可否が関係します。ツールがなくても基本的な同期は妨げられません。

HTML ソースファイル（0.6.1+）

docs-sync はバインドされたディレクトリ内の .md と .html の両方を取り込みます。HTML ファイルはレンダリングパイプラインを完全にスキップし、YApi の desc フィールドに書き込む前に <iframe srcdoc sandbox="allow-same-origin"> でラップされます。これにより、HTML のグローバルな <style> ルールや見出しサイズが YApi のページ表示に影響しないように分離されます。markdown フィールドには警告バナーとフェンス付きの HTML ソースが含まれ、チームメンバーが YApi の Web UI で誤ってドキュメントを編集して desc を上書きしないようにします。

• HTML は自己完結している必要があります（インライン CSS、base64／CDN 画像など）。CLI は相対リソースパスを書き換えません。
• HTML コンテンツはXSS サニタイズされません。信頼できるソースを使用してください。iframe では allow-same-origin のみが指定され（allow-scripts は指定されません）、埋め込みの <script> タグは実行されません。
• iframe の高さは 1500px に固定されています。オーバーフローした内容は iframe 内でスクロールします。
• ディレクトリ内に foo.md と foo.html の両方がある場合、CLI は .html を使用して警告を表示します。警告を表示しないようにするには .md を削除してください。
• ウォッチモード（--watch）では、.md と .html の両方の変更を監視します。
• ハッシュの互換性：既存の .md ファイルのハッシュは以前と完全に同じです。0.5.x からアップグレードしても、不要な再プッシュは発生しません。
• 0.6.0 → 0.6.1 のアップグレード：0.6.0 は未加工の HTML を desc に書き込み、YApi ページのスタイルに影響を与えていました。0.6.1 にアップグレードした後、yapi docs-sync --force を一度実行し、影響を受けたドキュメントを iframe でラップした形式で上書きしてください。

インターフェース作成時のガードレール

• インターフェースを作成・更新する際は、必ず req_body_type を設定し（不明な場合は json を使用）、res_body を指定してください（JSON Schema を推奨します）。
• リクエスト／レスポンスの構造化フィールドは、自由記述の desc／markdown だけに記載せず、req_*／res_body に設定してください。