yapi

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

YApi interface docs

YApi 接口文档

Install / update

安装/更新

Preferred install / refresh flow:

bash

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

Preferred config bootstrap after skill install:

bash

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

Compatibility path when the user also wants to write

~/.yapi/config.toml

in one step:

bash

npm install -g @leeguoo/yapi-mcp
yapi install-skill --yapi-base-url=https://your-yapi-domain.com --yapi-auth-mode=global --yapi-email=YOUR_EMAIL --force

推荐的安装/更新流程：

bash

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

安装skill后推荐的初始化配置流程：

bash

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

编写，可以使用兼容方案：

bash

npm install -g @leeguoo/yapi-mcp
yapi install-skill --yapi-base-url=https://your-yapi-domain.com --yapi-auth-mode=global --yapi-email=YOUR_EMAIL --force

Command policy

命令使用规则

Prefer

yapi

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

bash

yapi -h

优先使用

yapi

命令。如果命令不存在，回退到一次性npx命令，无需强制全局安装：

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
npx skills add leeguooooo/cross-request-master -y -g

npx -y -p @leeguoo/yapi-mcp yapi -h


下面的命令示例中，`yapi`均可替换为`npx -y -p @leeguoo/yapi-mcp yapi`。当CLI版本比已安装的skill快照版本更新时，`yapi`会发出警告并提示重新运行：

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

compatibility:

npx -y -p @leeguoo/yapi-mcp yapi install-skill --force

undefined

npx -y -p @leeguoo/yapi-mcp yapi install-skill --force

undefined

Setup / auth bootstrap

配置与身份认证初始化

Read configured
```
base_url
```
from
```
~/.yapi/config.toml
```
when available.
If config is missing, prefer browser login bootstrap:

bash

yapi login --base-url https://your-yapi-domain.com --browser

如果存在
```
~/.yapi/config.toml
```
，优先读取其中配置的
```
base_url
```
。
如果没有配置，优先使用浏览器登录初始化：

bash

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. If the user provides email/password, global auth also works:
```bash
yapi login --base-url https://your-yapi-domain.com --email you@example.com --password '***'

Validate login before deeper operations:

bash

yapi whoami

yapi login --base-url https://your-yapi-domain.com --login-url https://your-yapi-domain.com/

3. 如果用户提供邮箱/密码，也可以使用全局认证：
```bash
yapi login --base-url https://your-yapi-domain.com --email you@example.com --password '***'

执行更深层操作前先验证登录状态：

bash

yapi whoami

Quick workflow

快速工作流

If user gives a YApi URL, verify it belongs to configured
```
base_url
```
.
Confirm auth (
```
yapi whoami
```
), then run
```
yapi login --browser
```
when needed (open base URL, finish login in browser, then press Enter to sync cookie).
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.
If docs sync still hits
```
413
```
, note that CLI already retries the file with
```
--mermaid-classic
```
; if it still fails, split the doc or reduce embedded diagrams.

如果用户提供了YApi URL，校验其是否属于配置的
```
base_url
```
。
确认认证状态（执行
```
yapi whoami
```
），需要时运行
```
yapi login --browser
```
（打开基础URL，在浏览器中完成登录后按回车键同步Cookie）。
通过
```
api_id
```
/关键词/分类解析目标接口。
先拉取原始JSON，再汇总信息：请求方法、路径、请求头、参数、请求体、响应结构/示例。
文档同步任务先执行
```
--dry-run
```
预览，再执行实际同步。
如果文档同步仍然返回
```
413
```
错误，请注意CLI已经尝试用
```
--mermaid-classic
```
参数重试该文件；如果仍然失败，请拆分文档或减少内嵌图表。

URL detection

URL检测

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

bash

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

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
```

Prefer direct lookup when
```
api_id
```
exists:

bash

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

从
```
~/.yapi/config.toml
```
读取配置的
```
base_url
```
。

bash

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

如果URL源匹配

base_url

，从路径中提取ID：

```
/project/123/...
```
->
```
project_id=123
```
```
.../api/456
```
->
```
api_id=456
```
```
.../api/cat_789
```
->
```
catid=789
```

存在
```
api_id
```
时优先直接查询：

bash

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

Common commands

常用命令

bash

undefined

bash

undefined

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 --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


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

Browser login dependency:
```bash
agent-browser-stealth -V

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`

浏览器登录依赖：
```bash
agent-browser-stealth -V

install once if missing browser runtime

agent-browser-stealth install

undefined

agent-browser-stealth install

undefined

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 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

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).

yapi docs-sync bind remove --name projectA

removes a binding.

```
--source-file
```
overrides binding
```
source_files
```
;
```
--clear-source-files
```
clears the stored list on bind update.
```
--dry-run
```
prints per-file preview lines with Markdown/HTML/payload sizes before upload.
If upload hits
```
413 Payload Too Large
```
, the CLI first retries that file with
```
--mermaid-classic
```
, then reports payload size, parsed server limit (when available), and the largest Mermaid block if it still fails.
Mermaid/PlantUML/Graphviz/D2 rendering depends on local tool availability; missing tools do not block basic sync.

绑定模式（推荐）：

bash

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渲染依赖本地工具是否可用，缺少工具不会阻塞基础同步功能。

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
```
.

创建/更新接口时，始终设置
```
req_body_type
```
（不确定时用
```
json
```
）并提供
```
res_body
```
（优先使用JSON Schema）。
将结构化的请求/响应字段放在
```
req_*
```
/
```
res_body
```
中，不要仅放在自由文本的
```
desc
```
/
```
markdown
```
里。