YApi interface docs

Command policy

Prefer yapi command. If missing, fallback to one-shot npx without forcing global install:

yapi -h
# fallback:
npx -y @leeguoo/yapi-mcp -h

In command examples below, yapi can be replaced by npx -y @leeguoo/yapi-mcp.

Quick workflow

1. If user gives a YApi URL, verify it belongs to configured base_url.
2. Confirm auth (yapi whoami), then run yapi login only when needed.
3. Resolve target by api_id / keyword / category.
4. Fetch raw JSON first, then summarize: method, path, headers, params, body, response schema/examples.
5. For docs sync tasks, do --dry-run first, then real sync.

URL detection

1. Read configured base_url from ~/.yapi/config.toml.

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

2. If URL origin matches base_url, extract IDs from path:
   • /project/123/... -> project_id=123
   • .../api/456 -> api_id=456
   • .../api/cat_789 -> catid=789
3. Prefer direct lookup when api_id exists:

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

Common commands

# version/help
yapi --version
yapi -h

# auth
yapi whoami
yapi login

# 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

Config cache locations:

• Config: ~/.yapi/config.toml
• Auth cache: ~/.yapi-mcp/auth-*.json

Docs sync

Binding mode (recommended):

yapi docs-sync bind add --name projectA --dir docs/release-notes --project-id 267 --catid 3667
yapi docs-sync --binding projectA --dry-run
yapi docs-sync --binding projectA

Notes:

• Binding file: .yapi/docs-sync.json
• Mapping outputs: .yapi/docs-sync.links.json, .yapi/docs-sync.projects.json, .yapi/docs-sync.deployments.json
• Default behavior syncs changed files only; use --force for full sync.
• Compatible with directory .yapi.json config as fallback (without binding).
• Mermaid/PlantUML/Graphviz/D2 rendering depends on local tool availability; missing tools do not block basic sync.

Interface creation guardrails

• Always set req_body_type (use json if unsure) and provide res_body (prefer JSON Schema) when creating/updating interfaces.
• Put structured request/response fields in req_* / res_body, not only in free-text desc/markdown.