Swagger2 Project CLI

自动初始化 Swagger 配置和模板，用终端命令生成 API 客户端代码。

新版交互与两步流程（0.1.1，待发布 npm）

配置改为 url（下载地址）和 doc（本地 JSON）：先 npm run api:fetch，再 npm run api:gen。旧版本的 --input 参数改用 --url 或 --doc。

运行 swagger2-cli init 后，语言菜单默认选中 TypeScript，支持 ← → / ↑ ↓ 切换、Enter 确认。文本输入显示真实默认值，直接回车采用；请求模块默认值随语言变化。按 Ctrl+C 或在选择菜单按 Esc 可取消，取消时不会写入配置。

--preset javascript 会将 JavaScript 设为菜单初始选项；init -y 和非交互终端继续使用原有参数/默认值流程。

npm 目前已发布的 0.1.0 不包含本页的新流程。请先按下方源码打包方式安装 0.1.1。

功能

• init：交互式或参数式创建配置、模板和 npm scripts。
• fetch：从 url 下载 JSON，保存到本地 doc。
• gen：只读取本地 doc，生成 TypeScript、JavaScript 或 Dart 文件，不访问网络。
• 保留已有 npm scripts，拒绝覆盖手写文件，生成失败时保留旧产物。

本项目是独立 CLI 封装，解析和渲染依赖 [email protected]。npm 包名为 swagger2-project-cli，命令名为 swagger2-cli。

快速开始

环境要求：Node.js ^20.19.0 || >=22.12.0 和 npm。

1. 全局安装

npm ci
npm pack
npm install -g ./swagger2-project-cli-0.1.1.tgz
swagger2-cli --version

在本仓库目录执行上述命令。发布 0.1.1 后，也可以临时初始化：

npx [email protected] init

临时 npx 初始化后，日常运行 npm scripts 仍需全局或项目内安装 CLI。

2. 在业务项目初始化

cd /path/to/your-project
swagger2-cli init -y \
  --preset typescript \
  --url http://localhost:8080/v3/api-docs \
  --output ./src/api/generated

npm run api:fetch
npm run api:gen
npm install axios@^1.20.0

需要交互式引导时，执行 swagger2-cli init。request 路径支持方向键选择常用位置或自定义输入；非交互方式可用 --request-file ./src/utils/request.ts。

初始化创建 swagger2.config.mjs、scripts/swagger2.template.mjs，并向 package.json 添加 api:fetch / api:gen。TS/JS 默认在首次 gen 时创建 src/api/request.ts / .js，供 React、Vue 共用；后续保留手动配置。指定 --request-import 时使用项目已有封装。

安装方式怎么选？

• 个人使用、多个项目共用命令：全局安装 npm install -g，这是本手册的默认流程。
• 团队和 CI：项目内安装 npm install -D，提交 lockfile 固定版本，避免全局升级影响其他项目。
• 临时试用：通过 npx --package=安装包路径 swagger2-cli init 执行；之后的 npm scripts 仍需全局或项目内安装工具。

三种方式使用同一个 CLI，不需要不同版本。npm scripts 优先使用项目内的命令，其次查找 PATH 中的全局命令。全局命令需要 npm 的全局可执行目录在 PATH 中。

源码开发者也可以执行 npm ci 和 npm pack，再通过 npm install -g ./swagger2-project-cli-0.1.1.tgz 安装本地包。

文档

• React / Vue 可配置请求封装：基于旧 hongmeng-admin-vue3 的行为整理，含核心代码和接入示例。

• 完整使用手册：安装、初始化参数、配置、离线生成、模板和常见限制。

• 开发说明：模块职责、验证和打包流程。

• 更新记录

• 上游源码分析

验证与限制

npm run check
npm test

测试覆盖 Swagger 2 / OpenAPI 3 示例、TS 编译、JS 语法、Dart 文件生成、HTTP 错误处理、重复生成、输出保护和锁文件。Dart 产物未经过 Dart analyzer；复杂 Schema、部分状态码和 HTTP 方法仍受上游解析器限制，接入业务前需验证生成代码。

模板沿用上游 MIT 许可，完整文本位于初始化生成的模板头部注释，不再生成独立声明文件。

Terminal output

CLI prompts, help and validation messages are in English. All four arrow keys switch choices; Enter confirms. Completed prompts collapse to one-line answers. Invalid URL and request-path input can be corrected without restarting. Download and generation steps animate on interactive terminals; completion summaries use colored borders. Next-step commands follow the project package manager (packageManager field or lockfile). Piped output uses plain text. NO_COLOR disables colors and animations. Request runtime messages remain configurable in the generated source. No automatic update checks or download progress percentage are implemented.