Yapi

核心用法

YApi MCP Skill 是专为 YApi 接口管理平台设计的命令行工具集，主要服务于两大场景：接口文档查询与本地文档同步。

接口查询流程

1. URL识别：自动解析用户粘贴的YApi链接，匹配配置的base_url后提取project_id、api_id或catid
2. 身份确认：通过yapi whoami验证登录状态，按需执行yapi login
3. 多维检索：支持关键词搜索（yapi search）、单接口详情（--path /api/interface/get）、分类列表（--path /api/interface/list_cat）
4. 结果结构化：返回包含HTTP方法、Path、Headers、请求参数、Body定义、响应Schema及示例的完整文档

文档同步机制（推荐绑定模式）

# 建立项目绑定
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，支持增量同步（默认）与强制全量（--force）。

显著优点

• 深度集成YApi生态：原生支持YApi的权限模型与接口结构，无需二次解析
• 双模式灵活查询：既支持精确的api_id直达，也支持关键词模糊搜索
• 本地化工作流：绑定机制允许将接口文档与代码仓库的Markdown文件关联，实现文档即代码
• 安全可控：--dry-run预览机制避免误操作；配置与凭证分离存储（~/.yapi/config.toml与~/.yapi-mcp/auth-*.json）

潜在局限

• 外部依赖限制：Mermaid/PlantUML/Graphviz/D2图表渲染需本地安装对应工具，缺失时降级为纯文本
• 配置前置要求：必须预先配置base_url与登录凭证，首次使用门槛较高
• Node生态绑定：底层基于@leeguoo/yapi-mcp包，需Node.js环境（提供npx降级方案）
• 非通用标准：专用于YApi平台，无法直接迁移至Swagger/Knife4j等其他文档系统

适合人群

• 前端开发者：需要快速查阅后端接口定义，核对字段类型与枚举值
• 后端工程师：通过本地Markdown维护接口文档，需同步至YApi平台
• 技术写作/PM：批量导出接口文档用于发布说明或对外交付
• CI/CD维护者：在流水线中自动化接口文档同步与校验

常规风险

| 风险点 | 缓解措施 |

|--------|----------|

| 凭证泄露 | 认证信息存储于独立JSON文件，避免进入Git仓库 |

| 误覆盖线上文档 | 强制`--dry-run`预览；生产同步建议配合代码Review |

| 接口字段漂移 | 建立`req_body_type`/`res_body`填写规范，减少纯文本描述 |

| 同步冲突 | 绑定机制限定同步范围，避免跨项目误操作 |

核心用法

YApi Skill 是一款面向 API 文档管理的工具型技能，主要解决开发团队在 YApi 平台与本地文档之间的信息同步与查询问题。核心工作流程包括：验证 YApi URL 归属、确认用户身份认证、通过 API ID 或关键词定位目标接口、获取原始 JSON 数据并生成结构化摘要，以及执行文档的双向同步任务。

用户可通过自然语言指令触发技能，如"查询 YApi 接口文档"或直接粘贴符合配置的 YApi URL。技能支持多种命令模式：版本查询、身份认证、关键词搜索、单接口详情获取、分类列表查询等。文档同步功能提供绑定模式（推荐），允许将特定项目与本地目录建立持久映射，实现增量同步与全量强制同步的灵活控制。

显著优点

本地化集成深度：技能设计充分考虑了与现有开发工作流的融合，通过 ~/.yapi/config.toml 读取配置，支持 npx 零安装快速启动，降低了团队采纳门槛。

双向同步能力：不仅支持从 YApi 拉取文档，更能将本地 Markdown 文档推送至 YApi 平台，解决文档分散管理的痛点。--dry-run 预览机制有效避免误操作风险。

结构化输出：自动解析接口的请求方法、路径、头部、参数、请求体及响应结构，生成人类可读的技术摘要，减少人工阅读原始 JSON 的负担。

灵活的标识解析：智能识别 URL 中的 project_id、api_id、catid 等标识，支持直接查询与关键词搜索双模式，适应不同使用场景。

潜在缺点与局限性

外部依赖不可控：核心功能依赖 npm 包 @leeguoo/yapi-mcp，其版本迭代、安全更新与长期维护由第三方掌控，存在供应链风险。

渲染工具依赖：Mermaid、PlantUML、Graphviz、D2 等图表渲染依赖本地环境预装，缺失时降级为纯文本，影响文档可读性体验。

个人维护者风险：发布者为个人开发者，相比企业级产品，在技术支持响应、bug 修复时效、功能路线图透明度方面存在不确定性。

认证信息本地存储：YApi Token 以文件形式缓存在本地，若设备共享或权限配置不当，可能导致凭证泄露。

适合的目标群体

• 后端开发工程师：需要频繁查阅接口契约、确认字段定义的开发人员
• 技术文档工程师：负责维护 API 文档、推动文档即代码（Docs as Code）实践的文档从业者
• 前后端协作团队：需要确保 Mock 数据、接口文档与实现代码一致性的跨职能团队
• DevOps/平台工程师：构建内部开发者平台、集成 YApi 至 CI/CD 流程的基础设施团队

使用风险

供应链安全：建议在使用前审查 @leeguoo/yapi-mcp 的 npm 发布历史、GitHub 源码仓库及社区反馈，确认无恶意代码注入历史。

配置泄露风险：~/.yapi/config.toml 与认证缓存文件需设置 0600 权限，避免多用户环境下的信息暴露。

误同步风险：文档同步操作可能影响线上 YApi 项目，务必遵循 --dry-run 先行预览的最佳实践，并在版本控制完善的仓库中操作。

Token 权限管控：yapi login 获取的 Token 可能具备项目级甚至实例级权限，建议在 YApi 后台创建受限角色的专用 Token，遵循最小权限原则。