npm package: @karry.sun/yapi-gen
Description: 基于 yapi-to-typescript 的 YApi 前端代码生成 CLI，支持可配置的请求适配器与多项目复用
Latest version: 0.3.3

# yapi-gen

基于 [yapi-to-typescript](https://github.com/fjc0k/yapi-to-typescript) 的 YApi 接口代码生成 CLI，支持可配置的请求适配器、目录映射与按需生成。适用于 Vite、Nuxt、Vue 等不同请求封装。

---

## 安装

```bash
pnpm add -D @karry.sun/yapi-gen
```

本包已内置 yapi-to-typescript，无需单独安装。

---

## 快速开始

### 1. 初始化

```bash
pnpm yapi-gen init
```

会生成：

- `yapi-gen.config.ts`：主配置（serverUrl、token、requestAdapter 等）
- `src/yapi/gen-api-mapping.json`：分类→目录名映射（可手动维护）

### 2. 修改配置

编辑 `yapi-gen.config.ts`，至少修改：

- `serverUrl`：YApi 服务器地址
- `projects[0].token`：项目 token（建议用 `process.env.YAPI_TOKEN`）

### 3. 生成接口

```bash
pnpm yapi-gen
```

或在 `package.json` 中配置 `"gen:api": "yapi-gen"`，然后执行 `pnpm gen:api`。

---

## 请求适配方式

| 方式 | 说明 |
|------|------|
| `'axios'` | 封装 axios/defHttp 的项目，自动生成 `src/yapi/request.ts` |
| `'nuxt-bbm'` | Nuxt 项目，使用 `#imports` 或 `@bitunix/bbm` |
| `'custom'` | 自定义，需配置 `requestFunctionFilePath` 指向项目内 request 文件 |

**axios 示例**：`requestAdapter: { type: 'axios', axiosInstancePath: '/@/utils/http/axios' }`

**nuxt-bbm 示例**：`requestAdapter: { type: 'nuxt-bbm', requestImportPath: '#imports' }`

---

## 目录映射与按需生成

### 命令用法

```bash
# 全量生成
pnpm yapi-gen

# 按分类生成
pnpm yapi-gen cat_401
pnpm yapi-gen cat_401 cat_413                   # 多个分类（空格分隔）
pnpm yapi-gen cat_401,cat_413                   # 多个分类（逗号分隔）
pnpm yapi-gen cat_401=financialReconciliation   # 指定目录名并写入映射

# 批量映射并拉取多个分类
pnpm yapi-gen cat_401=financialReconciliation,cat_413=specialAccount

# 仅应用映射（只重命名目录，保留内容，不拉取接口）
pnpm yapi-gen --map-only cat_401=financialReconciliation,cat_413=specialAccount

# 按接口生成（合并模式）
pnpm yapi-gen 2116
pnpm yapi-gen 2113 2116                         # 多个接口（空格分隔）
pnpm yapi-gen 2113,2116                         # 多个接口（逗号分隔）
pnpm yapi-gen 2116 --map cat_413=specialAccount

# 多接口 + 多映射（同时更新多个接口并应用映射）
pnpm yapi-gen 2113,2116 --map cat_413=specialAccount,cat_401=commonCategory

# 自定义路径
pnpm yapi-gen --output-dir src/yapi --mapping-file src/yapi/gen-api-mapping.json
```

### 映射文件

- **路径**：`src/yapi/gen-api-mapping.json`（默认）
- **格式**：`{ "cat_401": "financialReconciliation", "cat_413": "specialAccount" }`
- **优先级**：命令行 > 配置文件 > 默认 `cat_xxx`
- **映射变更时**：旧目录会自动重命名为新目录名，目录内文件内容保留
- **仅改目录名**：使用 `--map-only` 可只重命名目录并保存映射，不执行接口拉取

```json
// src/yapi/gen-api-mapping.json（由业务维护）
{
  "cat_401": "publicCategory",
  "cat_413": "specialAccountAsset"
}
```

---

## 配置说明

| 字段 | 说明 | 必填 |
|------|------|------|
| `serverUrl` | YApi 服务器地址 | 是 |
| `serverType` | `'yapi'` \| `'swagger'` | 否 |
| `requestAdapter` | `'axios'` / `'nuxt-bbm'` / `'custom'` | 否 |
| `requestFunctionFilePath` | 自定义 request 文件路径 | custom 时必填 |
| `outputFilePath` | 生成文件路径或函数，不填时默认按 outputDir + 分类映射生成 | 否 |
| `outputDir` | 生成根目录，默认 `src/yapi` | 否 |
| `projects` | 项目列表（token、categories） | 是 |
| `dataKey` | 业务数据字段（如 `'result'` / `'data'`），axios/nuxt-bbm 适配器会据此从响应中解包业务数据 | 否 |
| `preproccessInterface` | 预处理接口：可过滤或改写。不填时已内置按 YTT_INTERFACE_IDS / YTT_CATEGORY_IDS 过滤（支持按接口/分类生成） | 否 |

---

## 配置文件查找顺序

`yapi-gen.config.ts`、`yapi-gen.config.mts`、`yapi-gen.config.cts`、`yapi-gen.config.js`、`yapi-gen.config.mjs`、`yapi-gen.config.cjs`、`.yapi-genrc.ts`、`.yapi-genrc.mts`、`.yapi-genrc.js`、`.yapi-genrc.mjs`

---

## License

MIT