162 lines
3.3 KiB
Markdown
162 lines
3.3 KiB
Markdown
# 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
|
||
```
|