YApi interface docs
Command policy
Prefer yapi command. If missing, fallback to one-shot npx without forcing global install:
CODEBLOCK0
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. - Confirm auth (
yapi whoami), then run yapi login only when needed. - Resolve target by
api_id / keyword / category. - Fetch raw JSON first, then summarize: method, path, headers, params, body, response schema/examples.
- 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:
CODEBLOCK2
Common commands
CODEBLOCK3
Config cache locations:
- - Config: INLINECODE18
- Auth cache: INLINECODE19
Docs sync
Binding mode (recommended):
CODEBLOCK4
Notes:
- - Binding file: INLINECODE20
- Mapping outputs:
.yapi/docs-sync.links.json, .yapi/docs-sync.projects.json, INLINECODE23 - 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.
YApi 接口文档
命令策略
优先使用 yapi 命令。若缺失，则回退到一次性 npx 执行，不强制全局安装：
bash
yapi -h
回退方案：
npx -y @leeguoo/yapi-mcp -h
在以下命令示例中，yapi 可替换为 npx -y @leeguoo/yapi-mcp。
快速工作流
- 1. 若用户提供 YApi URL，验证其属于已配置的 baseurl。
- 确认认证状态（yapi whoami），仅在需要时执行 yapi login。
- 通过 apiid / 关键词 / 分类解析目标。
- 先获取原始 JSON，再总结：方法、路径、请求头、参数、请求体、响应结构/示例。
- 对于文档同步任务，先执行 --dry-run，再进行实际同步。
URL 检测
- 1. 从 ~/.yapi/config.toml 读取已配置的 base_url。
bash
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 时，优先直接查找：
bash
yapi --path /api/interface/get --query id=
常用命令
bash
版本/帮助
yapi --version
yapi -h
认证
yapi whoami
yapi login
搜索/获取
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/config.toml
- 认证缓存：~/.yapi-mcp/auth-*.json
文档同步
绑定模式（推荐）：
bash
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
注意事项：
- - 绑定文件：.yapi/docs-sync.json
- 映射输出：.yapi/docs-sync.links.json、.yapi/docs-sync.projects.json、.yapi/docs-sync.deployments.json
- 默认行为仅同步变更文件；使用 --force 进行全量同步。
- 兼容目录 .yapi.json 配置作为回退方案（无绑定时）。
- Mermaid/PlantUML/Graphviz/D2 渲染依赖本地工具可用性；缺失工具不会阻塞基本同步。
接口创建规范
- - 创建/更新接口时，务必设置 reqbodytype（不确定时使用 json）并提供 resbody（优先使用 JSON Schema）。
- 将结构化的请求/响应字段放入 req* / res_body，而非仅放在自由文本的 desc/markdown 中。
