# yx-generate-api

`yx-generate-api` 是一个独立的 Node CLI，用来把 Swagger/OpenAPI 接口生成为前端 API 文件，并把 `generated/index.js` 的导出同步到外部入口文件中。

## 能力

- 根据 Swagger/OpenAPI JSON 生成模块化 API 文件
- 自动生成 `generated/index.js`
- 把生成目录的导出同步到外部 `index.js`
- 支持把内部 `generated/index.js` 原文写入注释区块
- 支持 `generate`、`sync`、`gen`、`init`
- 通过配置文件复用到不同项目

## 安装

可以直接从 Git 安装到业务项目：

```bash
npm install -D git+https://gitea.23544.com/wangyang/yx_generate_api_js.git
```

也可以先在本仓库开发，再通过 `npm pack` 或私有 npm 发布给其他项目。

## 快速开始

在你的业务项目根目录执行：

```bash
npx yx-generate-api init
```

这个命令会生成：

- `yx-generate-api.config.mjs`
- `run-yx-generate-api.bat`

然后根据你的项目结构修改配置文件。

## 配置示例

```js
export default {
  swaggerUrl: 'http://127.0.0.1:8080/swagger/v1/swagger.json',
  outputDir: 'src/api/aixue/generated',
  externalIndexFile: 'src/api/aixue/index.js',
  requestImport: '../request',
  paramStyle: 'object',
  sync: {
    enabled: true,
    includeGeneratedIndexSnapshot: true,
  },
}
```

## 命令

### 1. 初始化模板

```bash
npx yx-generate-api init
```

可选参数：

```bash
npx yx-generate-api init --force
```

### 2. 生成 API

```bash
npx yx-generate-api generate
```

只生成单个模块：

```bash
npx yx-generate-api generate Curriculum
```

生成多个模块：

```bash
npx yx-generate-api generate class-assignment Ranking
```

带参数：

```bash
npx yx-generate-api generate --modules=Curriculum,class-assignment
npx yx-generate-api generate --url=http://xxx/swagger/v1/swagger.json
npx yx-generate-api generate --paramStyle=positional
```

### 3. 只同步外部导出

```bash
npx yx-generate-api sync
```

### 4. 先生成再同步

```bash
npx yx-generate-api gen
```

## Windows 双击使用

`init` 默认会创建 `run-yx-generate-api.bat`，你可以直接双击它。

它内部会执行：

```bat
npx yx-generate-api gen
```

也可以在命令行里带参数：

```bat
run-yx-generate-api.bat Curriculum
run-yx-generate-api.bat --modules=Curriculum,class-assignment
```

## 配置说明

### 顶层配置

- `swaggerUrl`: Swagger/OpenAPI JSON 地址
- `outputDir`: 生成目录，相对配置文件所在目录
- `externalIndexFile`: 外部入口文件路径，相对配置文件所在目录
- `requestImport`: 生成文件中的 `request` 导入路径
- `paramStyle`: `object` 或 `positional`
- `sync`: 同步外部入口文件的规则

### sync 配置

- `enabled`: 是否启用同步
- `blockStart`: 受管注释块开始标记
- `blockEnd`: 受管注释块结束标记
- `includeGeneratedIndexSnapshot`: 是否把 `generated/index.js` 内容写入注释
- `snapshotTitle`: 快照注释标题
- `exportFrom`: 手动指定外部入口中的 `export * from '...'`

## 当前约定

默认会：

1. 生成 `outputDir/index.js`
2. 在 `externalIndexFile` 里写入受管区块
3. 受管区块包含：
   - 同步来源注释
   - `generated/index.js` 内容快照注释
   - `export * from '...'`

## 本地开发

在工具仓库执行：

```bash
node ./bin/yx-generate-api.js --help
```