yapi

YApi 接口文档

安装 / 更新

推荐的安装 / 刷新流程：

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

安装 skill 后推荐的配置初始化方式：

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 命令。如果找不到，则回退到一次性 npx，不要强制全局安装：

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

在下面的命令示例中，可以将 yapi 替换为 npx -y -p @leeguoo/[email protected] yapi。 当 CLI 版本比已安装的 skill 快照更新时，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）→ 参见下文的 ## Find interface by HTTP path。yapi search 不会索引路径，此情况不要使用它。
   • C. 产品关键词（语音房列表、voice room）→ 使用关键词扩展执行 yapi search（参见 ## Keyword expansion）。
   • 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 路径查找接口

当用户提供的是 HTTP 端点路径（例如 /api/auth/token，而不是 YApi 页面 URL）时，yapi search 会返回空结果，因为 YApi 的项目搜索不会索引接口路径。改用内置 --path 过滤器执行 yapi interface list-menu——由 CLI 进行过滤，无需使用 shell 管道。

必需输入：项目 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 网页界面编辑文档（这会覆盖 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）。
• 将结构化的请求/响应字段放入 req_* / res_body，不要只写在自由文本 desc/markdown 中。