# API Skill Web 端

[English](https://unpkg.com/apiskill@latest/docs/web.md) / [中文](https://unpkg.com/apiskill@latest/docs/web.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/web.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/web.ja.md)

## 启动

从 npm 安装后启动：

```bash
npm install -g apiskill
apiskill run web
```

Web、CLI 和 MCP 默认统一使用用户可写的 `~/.apiskill/cache`，共享同一份文档和版本。`--cwd` 只改变工作目录。需要隔离缓存时，必须为三个进程设置相同的绝对路径 `APISKILL_CACHE_DIR`。开发本仓库时也可以使用：

```bash
npm install
npm run dev
```

打开终端输出的本地地址。

页面右上角“缓存设置”用于查看当前会话位置和修改默认缓存地址。修改设置不会移动或删除已有文件；Web 重启后使用新地址。版本管理中每个版本的“更新缓存地址”会先展示当前位置和目标位置，确认后复制该版本，并保留源文件。

## 导入来源

“新建文档”弹窗通过 Tab 支持空白文档和四种导入方式：

- 直接导入 OpenAPI/Swagger JSON 或 YAML 地址。
- 爬取 Swagger UI、Knife4j、Redoc 页面。
- 上传本地 JSON/YAML 文件。
- 执行返回 OpenAPI/Swagger 文档的 curl 命令。
- 没有上游文档时从零创建空白文档。

导入后的文档会写入 `cache/versions/`，`cache/latest-import.json` 指向当前最新版本。

## 从零创建文档

使用“新建文档”按钮可以创建一份空白 OpenAPI 3.0 文档，填写文档名称、版本和可选描述。新文档会立即成为当前缓存版本。之后可以通过 Add/Edit/Delete API 动作，让 AI 助手或开发者逐步补充接口契约，不需要先导入第三方文档。

## MOCK 服务

已有 API 文档数据后，可以点击“启动MOCK服务”。Web 后端会根据当前文档的接口路径、HTTP 方法和响应 schema 启动本地 MOCK API 服务，访问对应接口时返回随机 JSON 数据。没有可用接口数据时，页面会提示先导入、爬取或新建文档。

## 查询和查看接口

可以按关键词、tag、HTTP method、是否有请求体过滤接口。打开接口 tab 后可以查看：

- 请求参数。
- 请求体字段。
- 响应字段。
- 适合直接给 AI 使用的 Markdown 上下文。
- 原始 OpenAPI JSON。

## 版本和手动接口维护

版本管理器可以切换或删除缓存版本。Add/Edit/Delete API 用于维护本地手动接口，适合上游文档缺字段、接口暂未同步、需要临时本地契约，或整套文档都要从零编写的场景。

手动接口和导入文档使用同一套版本化缓存，因此 CLI 和 MCP 服务可以立即查询到这些变更。