swaggerconvapi2

将 Swagger/OpenAPI (v2/v3) 转换为可用的 TypeScript 接口与请求代码，支持单文件/多文件输出、可自定义模板与钩子。

特性

• 支持 OpenAPI v2/v3，统一解析为标准 API 数据结构
• 单文件与多文件生成两种模式，适配不同项目结构
• 可配置模板（GET/POST/PUT/DELETE、文件头注入等）
• 钩子扩展：路径格式化、接口名格式化等
• 忽略字段、特殊路径、默认主体类型等可调

安装

• 项目内安装：yarn add swaggerconvapi2
• 全局安装：yarn global add swaggerconvapi2
• MacOS 提示：安装目录需包含 package.json，否则可能安装到系统全局目录。

快速开始

• 使用 npx（推荐）：
  • npx swapi <swagger-file|url> [configJSONPath] [选项]
  • 示例（本地）：npx swapi ./JSON/jwai.json
  • 示例（URL）：npx swapi https://example.com/openapi.json
  • 指定配置（两种方式）：
    • 位置参数：npx swapi ./openapi.json ./config/my.json
    • 或 --config：npx swapi ./openapi.json -c ./config/my.json
• 全局执行：
  • swapi <swagger-file|url> [configJSONPath] [选项]
  • 示例：swapi ./JSON/jwai.json
• 源码运行（开发者模式）：
  • node index.cjs <swagger-file|url> [configJSONPath] [选项]

运行时将所需的 JSON 与 config 文件放入工程目录，按需指定路径。config 可选，未提供时使用默认配置。

使用说明

• 项目发布版可直接使用 CLI（swapi / npx swapi）。
• 如果以源码方式参与开发，请先构建 dist 后再使用。

CLI 用法

• 用法：swapi <swagger-file|url> [config-file] [选项]
• 选项：
  • -c, --config 指定配置文件路径（优先级高于第二位置参数）
  • -h, --help 显示帮助信息
  • -v, --version 显示版本信息
• 说明：
  • 支持本地文件或 http/https URL（仅 JSON）
  • 未指定配置时，尝试自动加载 ./config/<swagger文件名>.json
  • 需要 Node 18+（内置 fetch）以获取远程文档

配置说明（示例为伪代码，按你的 JSON 字段填写）

// 输出相关
outDir = 'dist'; // 输出文件夹
outMode = 1; // 1 单文件；2 多文件
mainPath = ''; // 输出路径/目录
main = 'index'; // 入口文件名
paramsPath = ''; // params 类型输出路径
paramsMain = ''; // params 文件名前缀
modelPath = ''; // model 类型输出路径
modelMain = ''; // model 类型文件名

// 基础配置
baseUrl = ''; // 默认基础路径
baseUrlMode = 1; // 1 忽略 path 中的 baseUrl；2 统一添加 baseUrl

// 模板配置
topReference = TopReference; // 文件顶部注入模板
getTemplate = GetTemplate; // GET 模板
postTemplate = PostTemplate; // POST 模板
putTemplate = PutTemplate; // PUT 模板
deleteTemplate = DeleteTemplate; // DELETE 模板

// 钩子
formatPath = undefined; // 格式化 API 路径
formatInterfaceName = undefined; // 格式化接口名称

// API 相关
ignoreParams = []; // 需要忽略处理的字段
DefaultOption = {}; // API 对象默认 options
bufferPath = []; // 手动定义为 bufferRequest 的路径

// OpenAPI 解析
apiKey = 'api'; // api 默认引用名
version = '3'; // OpenAPI 版本
tagsKey = 'tags'; // Tags 对象 key
pathsKey = 'paths'; // Paths 对象 key
classTypesPath = undefined; // components.schemas(v3)/definitions(v2)
defaultResponseBody = 'form'; // 默认主体类型：json/application-json 或 form/multipart-form-data

模板替换规则

• 模板以字符串方式替换，连续的大括号会进行覆盖处理，替换完成后不保留大括号。
• 可用占位：{apiKey}、{name}（接口名）、{arg}（传参）、{request}（返回类型）、{protocol}（协议）、{path}（路径）、{option}（扩展配置）、{body}（主体）。
• paramsLocation/bodyLocation 不存在时将按 option 中的特定值处理。

开发与构建

• 代码入口：index.ts（参数解析、识别配置、执行并保存文件）
• 主逻辑：main.ts（统一配置 Option，解析 types/tags/apis，生成字符串与模板填充）
• 打包建议：rollup + esbuild（可参考 rollup.config.mjs）

设计说明

• 详细设计与模式说明见 README2.md（工厂/模板/策略/建造者/适配等）。

路线图

• 已完成：工厂化、配置文件、模板扩展、独立解析函数、TS 迁移、CLI 参数解析（minimist）、--help/--version、URL 输入支持
• 待迭代：更友好的错误提示
• 计划：线上化