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 安装到业务项目：

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

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

快速开始

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

npx yx-generate-api init

这个命令会生成：

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

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

配置示例

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. 初始化模板

npx yx-generate-api init

可选参数：

npx yx-generate-api init --force

2. 生成 API

npx yx-generate-api generate

只生成单个模块：

npx yx-generate-api generate Curriculum

生成多个模块：

npx yx-generate-api generate class-assignment Ranking

带参数：

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. 只同步外部导出

npx yx-generate-api sync

4. 先生成再同步

npx yx-generate-api gen

Windows 双击使用

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

它内部会执行：

npx yx-generate-api gen

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

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

本地开发

在工具仓库执行：

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