@zhuh/oig 8.9.1

package/README.md

@@ -0,0 +1,107 @@
+# @zhuh/oig
+
+[![npm version](https://img.shields.io/npm/v/@zhuh/oig.svg)](https://www.npmjs.com/package/@zhuh/oig)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> 从 OpenAPI/Swagger 规范自动生成 TypeScript API 客户端
+
+## 功能特性
+
+- 从 OpenAPI 协议直接生成高质量完整可用的 TS
+- 支持本地文件和远程 URL
+- 自动生成类型定义和 API 函数
+- 基于 axios 的 HTTP 客户端封装
+- 自动格式化生成的代码（Biome）
+- 批量生成多个 API
+
+## 安装
+
+```bash
+npm install -g @zhuh/oig
+# 或
+pnpm add -g @zhuh/oig
+```
+
+## 快速开始
+
+1. 创建配置文件 `src/api/openapi_api.json`：
+
+```json
+{
+  "api_addresses": [
+    {
+      "definition": "petstore",
+      "address": "https://petstore.swagger.io/v2/swagger.json"
+    }
+  ]
+}
+```
+
+2. 运行生成命令：
+
+```bash
+@zhuh/oig
+```
+
+3. 查看生成的文件：
+
+```
+src/api/petstore/
+├── _schemas.gen.ts      # 公共 schema
+├── pet.schema.ts        # Pet 相关 schema
+├── pet.ts               # Pet API 函数
+└── _export.ts           # 汇总导出
+```
+
+## 配置说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `definition` | string | 是 | 输出目录名 |
+| `address` | string | 是 | Schema 文件路径或 URL |
+| `generate` | boolean | 否 | 是否生成（默认 true） |
+
+## CLI 参数
+
+| 参数 | 说明 |
+|------|------|
+| `-s <path>` | 直接指定 schema 路径（兼容 v1） |
+| `-d` | 开发模式（显示详细警告） |
+
+## 生成的文件结构
+
+每个 definition 生成：
+
+- `_schemas.gen.ts` — 公共 schema（`#/components/schemas`）
+- `[tag].schema.ts` — 标签专用 schema
+- `[tag].ts` — 标签 API 实现（基于 axios）
+- `_export.ts` — 汇总导出文件
+
+## HTTP 客户端
+
+生成的代码使用 `src/api/_http.ts` 封装的 axios 实例：
+
+- 自动处理业务错误码（`data.code !== 0`）
+- 60 秒超时
+- 支持自定义配置
+
+## 开发
+
+```bash
+# 构建
+pnpm build
+
+# 格式化
+pnpm format
+```
+
+## 技术栈
+
+- TypeScript + Rollup
+- Biome（代码格式化）
+- @zhuh/orval（代码生成核心）
+- pnpm（包管理）
+
+## 许可证
+
+MIT

package/dist/index.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+import { readFile, access, mkdir, writeFile } from 'node:fs/promises';
+import { resolve, relative, parse } from 'node:path/posix';
+import * as p from '@clack/prompts';
+import { isString, kebab } from '@orval/core';
+import { normalizeOptions, resolveSpec, applyTransformer, _effect_getApiBuilder, getApiSchemas } from '@zhuh/orval';
+import { deleteAsync } from 'del';
+import { execa } from 'execa';
+import pLimit from 'p-limit';
+import pc from 'picocolors';
+
+const workspace = process.cwd();
+const args = process.argv;
+const ISDEV = args.includes('-d');
+const spin = p.spinner();
+async function loadConfig() {
+    const configFileRaw = await readFile(resolve('src/api', 'openapi_api.json'), 'utf8');
+    return JSON.parse(configFileRaw);
+}
+async function generateAPIFile(api) {
+    const { address, definition } = api;
+    const outdir = `src/api/${definition}`;
+    const outdirAbsolute = resolve(outdir);
+    const configOptions = await normalizeOptions({
+        input: address,
+        output: {
+            httpClient: 'axios',
+            target: outdirAbsolute,
+            override: {
+                mutator: {
+                    path: resolve('src/api/_http.ts'),
+                    name: '_http',
+                },
+            },
+        },
+    });
+    const spec = await resolveSpec(configOptions.input.target, configOptions.input.parserOptions);
+    const transformedOpenApi = await applyTransformer(spec, configOptions.input.override.transformer, workspace);
+    const { operations: apiOperations, schemas: apiSchemas } = await _effect_getApiBuilder({
+        input: configOptions.input,
+        output: configOptions.output,
+        context: {
+            target: isString(configOptions.input.target)
+                ? configOptions.input.target
+                : workspace,
+            workspace,
+            spec: transformedOpenApi,
+            output: configOptions.output,
+        },
+    });
+    // 建好文件夹
+    await access(outdirAbsolute)
+        .then(async () => {
+        try {
+            await deleteAsync([
+                `${outdir}/*`,
+                `!${outdir}/*/`,
+                `!${outdir}/_http.ts`,
+                `!${outdir}/openapi_api.json`,
+            ]);
+        }
+        catch (error) {
+            if (ISDEV) {
+                console.warn(`\n${pc.bgYellowBright(pc.green('只是警告'))}`, 'deleteAsync错误', error);
+            }
+        }
+    })
+        .catch(async (error) => {
+        if (ISDEV) {
+            console.warn(`\n${pc.bgYellowBright(pc.green('只是警告'))}`, `访问文件夹${outdirAbsolute}错误`, error);
+        }
+        await mkdir(outdirAbsolute, {
+            recursive: true,
+        });
+    });
+    const apiFileGenerates = [];
+    const limit = pLimit(8);
+    const exportFiles = [];
+    /**
+     * 所有的通用模型（#/components/schemas）不分组写入一个文件
+     */
+    const allCommonSchema = getApiSchemas({
+        input: configOptions.input,
+        output: configOptions.output,
+        target: isString(configOptions.input.target)
+            ? configOptions.input.target
+            : workspace,
+        workspace,
+        spec: transformedOpenApi,
+    });
+    const writeCommonSchema = async () => {
+        if (allCommonSchema.filter((c) => c.model).length === 0)
+            return;
+        await writeFile(resolve(outdirAbsolute, '_schemas.gen.ts'), allCommonSchema.map((s) => s.model).join('\n'));
+        exportFiles.push('_schemas.gen.ts');
+    };
+    const apiOperationValues = Object.values(apiOperations);
+    const tags = [...new Set(apiOperationValues.flatMap(({ tags }) => tags))];
+    tags.forEach((tag) => {
+        apiFileGenerates.push(limit(async () => {
+            const operations = apiOperationValues.filter(({ tags }) => tags.includes(tag));
+            /**
+             * 统计出tag用哪些接口函数，以及用到了哪些schema，schema有引用了哪些modelSchema
+             */
+            const implementations = operations.map(({ implementation }) => implementation);
+            /**
+             * 这是接口函数文件用到的通用schema
+             * [tag].ts import _schemas.gen.ts
+             */
+            let commonSchemaImports = [];
+            /**
+             * 这是接口函数文件用到的特用schema
+             * [tag].ts import [tag].schema.ts
+             */
+            const schemaImports = [];
+            /**
+             * 这是接口函数特用schema用到的通用schema
+             * [tag].schema.ts import _schemas.gen.ts
+             */
+            const schemaCommonImports = [];
+            operations
+                .flatMap(({ imports }) => imports)
+                .forEach((meta) => {
+                // 这是接口函数文件用到的通用schema
+                if (meta.schemaName) {
+                    if (!commonSchemaImports.find((s) => s.schemaName === meta.schemaName)) {
+                        commonSchemaImports.push(meta);
+                    }
+                    return;
+                }
+                // 这是接口函数文件用到的特用schema
+                if (!schemaImports.find((s) => s.name === meta.name)) {
+                    schemaImports.push(meta);
+                }
+                const target = apiSchemas.find((schema) => schema.name === meta.name);
+                if (target) {
+                    // 这是接口函数特用schema用到的通用schema
+                    schemaCommonImports.push(...target.imports.filter(({ name }) => name));
+                }
+            });
+            // 添加不是$ref的schema
+            schemaCommonImports.forEach((schemaCommon) => {
+                const exported = allCommonSchema
+                    .map((s) => s.name)
+                    .find((name) => name === schemaCommon.name);
+                if (!exported) {
+                    const target = apiSchemas.find((s) => s.name === schemaCommon.name);
+                    if (target) {
+                        allCommonSchema.unshift(target);
+                    }
+                }
+            });
+            // 把不存在的过滤掉
+            const allCommonSchemaName = allCommonSchema.map((s) => s.name);
+            commonSchemaImports = commonSchemaImports.map((schema) => {
+                if (!allCommonSchemaName.includes(schema.name)) {
+                    return {
+                        ...schema,
+                        name: '',
+                    };
+                }
+                if (schema.schemaName &&
+                    !allCommonSchemaName.includes(schema.schemaName)) {
+                    return {
+                        ...schema,
+                        schemaName: '',
+                    };
+                }
+                return { ...schema };
+            });
+            await Promise.all([
+                (async () => {
+                    // [tag].schema.ts
+                    const schemaRaw = `${schemaCommonImports.length === 0
+                        ? ''
+                        : `import type {${[...new Set(schemaCommonImports.map(({ name }) => name))].join(',')}} from './_schemas.gen'
+`}
+${[...new Set(schemaImports.map(({ name }) => name))].map((name) => apiSchemas.find((s) => s.name === name)?.model ?? '').join('\n')}
+`;
+                    if (schemaRaw.trim().length > 0) {
+                        await writeFile(resolve(outdirAbsolute, `${kebab(tag)}.schema.ts`), schemaRaw);
+                        exportFiles.push(`${kebab(tag)}.schema.ts`);
+                    }
+                })(),
+                (async () => {
+                    let mutatorPath = relative(outdir, 'src/api/_http');
+                    if (!mutatorPath.startsWith('..')) {
+                        mutatorPath = `./${mutatorPath}`;
+                    }
+                    // [tag].ts
+                    const implementationRaw = `import { _http } from '${mutatorPath}'
+${commonSchemaImports.length === 0
+                        ? ''
+                        : `import type {${[...new Set(commonSchemaImports.flatMap(({ name, schemaName }) => [name, schemaName]).filter(Boolean))].join(',')}} from './_schemas.gen'
+`}${schemaImports.length === 0
+                        ? ''
+                        : `import type {${[...new Set(schemaImports.map(({ name }) => name))].join(',')}} from './${kebab(tag)}.schema'
+`}
+${implementations.map((implementation) => implementation).join('\n')}`;
+                    if (implementationRaw.trim().length > 0) {
+                        await writeFile(resolve(outdirAbsolute, `${kebab(tag)}.ts`), implementationRaw);
+                        exportFiles.push(`${kebab(tag)}.ts`);
+                    }
+                })(),
+            ]);
+        }));
+    });
+    apiFileGenerates.push(limit(async () => await writeCommonSchema()));
+    await Promise.all(apiFileGenerates);
+    if (exportFiles.length > 0) {
+        await writeFile(resolve(outdirAbsolute, '_export.ts'), `${exportFiles.map((f) => `export * from './${parse(f).name}'`).join('\n')}
+`);
+    }
+    try {
+        await execa('pnpm', [
+            'biome',
+            'check',
+            '--write',
+            outdirAbsolute,
+            '--formatter-enabled=true',
+            '--javascript-formatter-quote-style=single',
+            '--semicolons=as-needed',
+            '--linter-enabled=false',
+        ]);
+    }
+    catch (error) {
+        if (ISDEV) {
+            console.warn(`\n${pc.bgYellowBright(pc.green('只是警告'))}`, 'biome格式化错误', error);
+        }
+    }
+}
+async function main() {
+    p.intro(`V_${pc.bgYellowBright(pc.green(ISDEV ? new Date().toLocaleString() : '8.9.1'))}`);
+    let config = null;
+    // 兼容版本1用法
+    const parseV1SchemaPath = () => {
+        const target = args.indexOf('-s');
+        if (target === -1)
+            return;
+        return args[target + 1];
+    };
+    const schemaPath = parseV1SchemaPath();
+    if (schemaPath) {
+        config = {
+            api_addresses: [
+                {
+                    address: schemaPath,
+                    definition: '',
+                },
+            ],
+        };
+    }
+    else {
+        config = await loadConfig();
+    }
+    const limit = pLimit(1);
+    const generates = config.api_addresses
+        .filter(({ generate }) => generate !== false)
+        .map((api) => limit(async () => {
+        const definition = api.definition || 'root';
+        spin.start(`正在生成：${definition}`);
+        await generateAPIFile(api).catch((error) => {
+            spin.stop(`⁉️ ${definition}`);
+            throw error;
+        });
+        spin.stop(`✅ ${definition}`);
+    }));
+    await Promise.all(generates);
+    p.outro('mymymytg 👏👏👏');
+}
+main().catch((error) => {
+    console.error('❌ 发生错误', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,64 @@
+{
+	"name": "@zhuh/oig",
+	"description": "从 OpenAPI/Swagger 规范自动生成 TypeScript API 客户端",
+	"keywords": [
+		"openapi",
+		"swagger",
+		"typescript",
+		"codegen",
+		"api",
+		"client",
+		"axios",
+		"orval",
+		"generator",
+		"cli"
+	],
+	"private": false,
+	"version": "8.9.1",
+	"type": "module",
+	"bin": {
+		"@zhuh/oig": "dist/index.js"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "rollup -c ./rollup.config.ts --configImportAttributesKey with",
+		"format": "biome check --write . --use-editorconfig=true"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.14",
+		"@rollup/plugin-commonjs": "^29.0.2",
+		"@rollup/plugin-node-resolve": "^16.0.3",
+		"@rollup/plugin-replace": "^6.0.3",
+		"@rollup/plugin-typescript": "^12.3.0",
+		"@types/node": "^25.6.0",
+		"axios": "^1.16.0",
+		"bumpp": "^11.1.0",
+		"openapi3-ts": "^4.5.0",
+		"rollup": "^4.60.3",
+		"tslib": "^2.8.1",
+		"typescript": "^5.9.3"
+	},
+	"dependencies": {
+		"@clack/prompts": "^1.3.0",
+		"@orval/core": "^8.9.1",
+		"@zhuh/orval": "8.9.1",
+		"del": "^8.0.1",
+		"execa": "^9.6.1",
+		"p-limit": "^7.3.0",
+		"picocolors": "^1.1.1"
+	},
+	"resolutions": {
+		"whatwg-url": "16.0.1"
+	},
+	"overrides": {
+		"whatwg-url": "16.0.1"
+	},
+	"pnpm": {
+		"onlyBuiltDependencies": [
+			"@biomejs/biome",
+			"esbuild"
+		]
+	}
+}