qxun-api-generator 1.0.0

package/bin/api-generator.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+const { program } = require("commander");
+const { version } = require("../package.json");
+
+program
+  .command("generate", { isDefault: true })
+  .version(version)
+  .description("Generate End-to-end type-safe APIs")
+  .option("-i, --input <input>", "api.json 所在路径，默认是项目根目录")
+  .option("--auth [auth]", "Authorization header 值（访问受保护的 swagger 地址时使用）")
+  .action(function (inputSchema) {
+    const options = program.opts();
+    const finalSchema = { ...inputSchema, ...options };
+    require("../lib")
+      .run(finalSchema)
+      .catch((err) => {
+        console.error("错误：", err);
+        process.exit(1);
+      });
+  });
+
+program.parse(process.argv);

package/lib/index.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = exports.writeFileSafely = void 0;
+const ajv_1 = require("ajv");
+const axios_1 = require("axios");
+const cp = require("child_process");
+const fs = require("fs");
+const mkdirp_1 = require("mkdirp");
+const path = require("path");
+
+const DEFAULT_DIR = "src/api";
+
+function checkResponseType(res) {
+    switch (res.headers["content-type"]) {
+        case "application/x-yaml":
+            return "YAML";
+        default:
+            return "JSON";
+    }
+}
+
+/**
+ * 安全写文件：自动创建所有中间目录
+ */
+async function writeFileSafely(filePath, data) {
+    await (0, mkdirp_1.mkdirp)(path.dirname(filePath));
+    return new Promise((resolve, reject) => {
+        fs.writeFile(filePath, data, (err) => {
+            if (err) reject(err);
+            else resolve();
+        });
+    });
+}
+exports.writeFileSafely = writeFileSafely;
+
+function deleteDirectory(dirPath) {
+    if (!fs.existsSync(dirPath)) return;
+    const files = fs.readdirSync(dirPath);
+    for (const file of files) {
+        const cur = `${dirPath}/${file}`;
+        if (fs.lstatSync(cur).isDirectory()) {
+            deleteDirectory(cur);
+        } else {
+            fs.unlinkSync(cur);
+        }
+    }
+    fs.rmdirSync(dirPath);
+}
+
+function replaceInFile(filePath, matcher, replacement) {
+    if (!fs.existsSync(filePath)) return;
+    const content = fs.readFileSync(filePath, "utf8");
+    fs.writeFileSync(filePath, content.replaceAll(matcher, replacement), "utf8");
+}
+
+/**
+ * 获取 Swagger 文件：
+ * - 本地路径 → 直接使用
+ * - 远端 URL → 下载保存到 _swaggers/ 目录后返回本地路径
+ */
+async function fetchSwagger(config, auth) {
+    const isLocal = !config.path.startsWith("http");
+    if (isLocal) return config;
+
+    const headers = {};
+    if (auth) headers["Authorization"] = auth;
+
+    const res = await axios_1.default.request({
+        method: "GET",
+        url: config.path,
+        headers,
+    });
+
+    const type = checkResponseType(res);
+    const ext = type === "YAML" ? ".yaml" : ".json";
+    const localFilePath = path.join(
+        process.cwd(),
+        config.outputDir || DEFAULT_DIR,
+        "_swaggers",
+        config.service + ext
+    );
+
+    const data = type === "JSON" ? JSON.stringify(res.data, null, 2) : res.data;
+    await writeFileSafely(localFilePath, data);
+
+    return { ...config, path: localFilePath };
+}
+
+async function generateApi(config) {
+    const destDir = path.join(process.cwd(), config.outputDir || DEFAULT_DIR, config.service);
+    console.log("输出目录：", destDir);
+    await (0, mkdirp_1.mkdirp)(destDir);
+
+    // 调用 openapi-generator CLI 生成 typescript-axios 代码
+    try {
+        cp.execSync(
+            `openapi-generator generate -g typescript-axios -i ${config.path} -o ${destDir}` +
+            ` --additional-properties=useSingleRequestParameter=true,ensureUniqueParams=true,stringEnums=true`,
+            { stdio: "inherit" }
+        );
+    } catch (e) {
+        console.error(e);
+        console.error('\n如果未安装 openapi-generator：请运行 `brew install openapi-generator`\n');
+        return;
+    }
+
+    const apiFile = `${destDir}/api.ts`;
+
+    // 替换 axios import → 项目自定义 http 客户端
+    replaceInFile(
+        apiFile,
+        `import globalAxios from 'axios';`,
+        config.httpPath ?? `import { http as globalAxios } from '../../utils/http'`
+    );
+
+    // 修正 AxiosPromise 类型（openapi-generator 6.x）
+    replaceInFile(
+        apiFile,
+        `import type { AxiosPromise, AxiosInstance, AxiosRequestConfig } from 'axios';`,
+        `import type { AxiosInstance, AxiosRequestConfig } from 'axios';\n` +
+        `  type AxiosPromise<T> = Promise<T extends {data?: any } ?  T['data'] : void>;`
+    );
+
+    // 修正 AxiosPromise 类型（openapi-generator 7.x）
+    replaceInFile(
+        apiFile,
+        `import type { AxiosPromise, AxiosInstance, RawAxiosRequestConfig } from 'axios';`,
+        `import type { AxiosInstance, AxiosRequestConfig } from 'axios';\n` +
+        `  type AxiosPromise<T> = Promise<T extends {data?: any } ?  T['data'] : void>;`
+    );
+    replaceInFile(apiFile, `RawAxiosRequestConfig`, `AxiosRequestConfig`);
+
+    // 修正 createRequestFunction 签名，兼容自定义 http 客户端
+    replaceInFile(
+        `${destDir}/common.ts`,
+        "export const createRequestFunction = function (axiosArgs: RequestArgs, globalAxios: AxiosInstance, BASE_PATH: string, configuration?: Configuration) {",
+        "export const createRequestFunction = function (axiosArgs: RequestArgs, globalAxios: any, BASE_PATH: string, configuration?: Configuration) {"
+    );
+
+    // 设置 BASE_PATH 为单一固定地址
+    replaceInFile(
+        `${destDir}/base.ts`,
+        `export const BASE_PATH = "http://localhost".replace(/\\/+$/, "");`,
+        `export const BASE_PATH = "${config.baseUrl ?? ''}";`
+    );
+
+    // 清理无用文件
+    deleteDirectory(`${destDir}/.openapi-generator`);
+    fs.unlink(`${destDir}/.gitignore`, () => void 0);
+    fs.unlink(`${destDir}/.npmignore`, () => void 0);
+    fs.unlink(`${destDir}/.openapi-generator-ignore`, () => void 0);
+    fs.unlink(`${destDir}/git_push.sh`, () => void 0);
+}
+
+async function run(inputSchema) {
+    const configPath = inputSchema.input ?? path.resolve(process.cwd(), "./api.json");
+
+    let config;
+    try {
+        config = require(configPath);
+    } catch (error) {
+        console.error("ERROR: 无法读取 api.json，请确认文件存在且格式正确");
+        process.exit(1);
+    }
+
+    // 校验配置格式
+    const ajv = new ajv_1.default();
+    const schema = fs.readFileSync(path.resolve(__dirname, "./schema.json"), { encoding: "utf-8" });
+    const validate = ajv.compile(JSON.parse(schema));
+    if (!validate(config)) {
+        console.error("ERROR: api.json 配置不合法", validate.errors);
+        process.exit(1);
+    }
+
+    const auth = inputSchema.auth;
+
+    console.log("\n生成中...");
+
+    const p = config.apis.map(async (api) => {
+        const resolved = await fetchSwagger(api, auth);
+        return generateApi(resolved);
+    });
+
+    const results = (await Promise.allSettled(p)).map((item, index) => ({
+        name: config.apis[index].service,
+        failed: item.status === "rejected",
+        reason: item.status === "rejected" ? item.reason : null,
+    }));
+
+    const success = results.filter((r) => !r.failed);
+    const failed  = results.filter((r) => r.failed);
+
+    process.stdout.write("\x1b[1A\x1b[K");
+    console.log("\n执行完毕，共 " + results.length + " 个服务");
+
+    if (success.length) {
+        console.log("\n✅ 成功生成：" + success.map((r) => r.name).join(", ") + "\n");
+    }
+    if (failed.length) {
+        console.log("\x1b[31m%s\x1b[0m", "❌ 生成失败：" + failed.map((r) => r.name).join(", ") + "\n");
+        failed.forEach((r) => console.error(r.reason));
+    }
+}
+exports.run = run;

package/lib/schema.json

@@ -0,0 +1,46 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "additionalProperties": false,
+    "properties": {
+        "$schema": {
+            "type": "string"
+        },
+        "apis": {
+            "description": "API 定义数组",
+            "items": {
+                "$ref": "#/definitions/API"
+            },
+            "type": "array"
+        }
+    },
+    "definitions": {
+        "API": {
+            "additionalProperties": false,
+            "properties": {
+                "service": {
+                    "description": "后端服务名称",
+                    "type": "string"
+                },
+                "outputDir": {
+                    "description": "输出目录",
+                    "type": "string"
+                },
+                "path": {
+                    "description": "swagger 路径，可以是本地路径也可以是远端地址",
+                    "type": "string"
+                },
+                "httpPath": {
+                    "description": "全局 http 文件的路径",
+                    "type": "string"
+                },
+                "baseUrl": {
+                    "description": "服务的 baseURL",
+                    "type": "string"
+                }
+            },
+            "required": ["service", "outputDir", "path", "httpPath"],
+            "type": "object"
+        }
+    },
+    "type": "object"
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "qxun-api-generator",
+  "version": "1.0.0",
+  "description": "从 Swagger / OpenAPI 生成端到端类型安全的 TypeScript API Client",
+  "main": "./lib/index.js",
+  "typings": "./lib/index.d.ts",
+  "bin": "./bin/api-generator.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "lib",
+    "bin"
+  ],
+  "license": "ISC",
+  "dependencies": {
+    "ajv": "^8.12.0",
+    "axios": "^1.4.0",
+    "commander": "^12.1.0",
+    "mkdirp": "^3.0.1"
+  }
+}