yapi

分类: 文档与知识管理 | 上传者: leeguooooo | 下载: 0 | 版本: v1.0（最新）

查询并同步YApi接口文档。当用户提及“yapi 接口文档”、YAPI 文档、询问请求/响应详细信息或需要文档同步时使用。当用户粘贴与配置的 base_url 匹配的 YApi URL 时也会触发。

更新日志: Source: GitHub https://github.com/leeguooooo/cross-request-master

目录结构

当前层级: tree/main/packages/yapi-mcp/skill-template/

📄 SKILL.md 3.5 KB

SKILL.md

---
name: yapi
description: Query and sync YApi interface documentation. Use when user mentions "yapi 接口文档", YAPI docs, asks for request/response details, or needs docs sync. Also triggers when user pastes a YApi URL that matches the configured base_url.
---

# YApi interface docs

## Command policy

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

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

In command examples below, `yapi` can be replaced by `npx -y -p @leeguoo/yapi-mcp yapi`.
When CLI version is newer than the installed skill snapshot, `yapi` warns and asks to rerun:

```bash
yapi install-skill --force
```

## 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 --browser` when needed (open base URL, finish login in browser, then press Enter to sync cookie).
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`.
```bash
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:
```bash
yapi --path /api/interface/get --query id=<api_id>
```

## Common commands

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

# auth
yapi whoami
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"
```

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

Browser login dependency:
```bash
agent-browser-stealth -V
# install once if missing browser runtime
agent-browser-stealth install
```

## Docs sync

Binding mode (recommended):
```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
```

Notes:
- Binding file: `.yapi/docs-sync.json`
- Mapping outputs: `.yapi/docs-sync.links.json`, `.yapi/docs-sync.projects.json`, `.yapi/docs-sync.deployments.json`
- When bindings live under the global `~/.yapi/docs-sync.json`, relative `--dir` values are resolved from the current git project root and stored as `$HOME`-relative paths.
- Default behavior syncs changed files only; use `--force` for full sync.
- Compatible with directory `.yapi.json` config as fallback (without binding).
- `--dry-run` prints per-file preview lines with Markdown/HTML/payload sizes before upload.
- If upload hits `413 Payload Too Large`, the CLI now reports payload size, parsed server limit (when available), and the largest Mermaid block.
- 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`.

登录后下载/点赞/收藏 ❤ 144 | ★ 0

yapi

目录结构

SKILL.md

举报内容

提示