@huchenghe/sdk-gen-core

English · 中文

从 OpenAPI/Swagger spec 生成可发布、类型完备的 TypeScript SDK —— 一条命令把 swagger.json 变成完整的 npm 包：封装好的 Axios client、自动发现的 API 注册表、MSW mock、版本同步、测试与文档。

它是从真实 SDK 生成实践中提炼出的框架无关核心：工具只消费 swagger 文件。 框架相关的 spec 提取（例如 NestJS 无头启动导出 swagger）由你自己的项目负责， 提取结果就是本工具的输入。

swagger.json ──► sdk-gen generate ──► ./sdk  （一个可发布的 npm 包）

特性

• 🔧 单一输入：swagger.json → 完整的 SDK 项目
• 🧩 OpenAPI Generator 作为生成引擎（默认 typescript-axios，可扩展）
• 🏗️ 自动生成包装层：client（Axios + 拦截器 + token）、api-registry（自动发现 *Api 类，从文件内容提取真实类名）、mock（MSW）、version（版本同步）、入口 index
• 🔖 版本同步：与你的 API 包版本保持一致
• ✅ 验证：发布前做一致性与安全检查
• 🧪 CLI 与程序化 API 双入口，附带单元 + 集成测试
• 🧰 应用运行时无 Java 依赖 —— 生成器 CLI 通过 npx 调用

安装

项目内安装（推荐 —— 配合配置文件与 CI 使用）

pnpm add -D @huchenghe/sdk-gen-core

全局安装（任意目录直接使用 sdk-gen 命令）

npm i -g @huchenghe/sdk-gen-core    # 或 pnpm add -g @huchenghe/sdk-gen-core

装好后任意目录都能直接运行：

sdk-gen generate -i swagger.json -o ./sdk
sdk-gen validate ./sdk
sdk-gen clean ./sdk

注意：generate 底层通过 npx 调用 openapi-generator（JVM），全局安装同样要求本机有 Java 8+ 和网络。versionSync 默认读取当前目录的 package.json 版本。

也可以直接从工具自身的 GitHub 仓库安装 —— prepare 会自动构建：

npm i -g github:<owner>/sdk-gen-core

CLI

# 从配置文件生成
sdk-gen generate --config sdk.config.ts

# 或使用内联参数
sdk-gen generate -i swagger.json -o ./sdk

# 顺便搭建 GitHub 发布（workflow + git init + gh 推送）
sdk-gen generate -i swagger.json -o ./sdk --github

# 校验 SDK 目录
sdk-gen validate ./sdk

# 清理可再生的生成产物
sdk-gen clean ./sdk

配置文件（sdk.config.ts）

import type { SdkGenConfig } from '@huchenghe/sdk-gen-core';

export default {
  swaggerFile: './swagger.json',
  outputDir: 'sdk',
  generator: 'typescript-axios',
  npmScope: '@my-org',
  npmPkgName: 'api-sdk',

  additionalProperties: {
    modelPropertyNaming: 'original',
    withSeparateModelsAndApi: 'true',
    modelPackage: 'models',
    apiPackage: 'apis',
    supportsES6: 'true',
    enumPropertyNaming: 'UPPERCASE',
    stringEnums: 'true',
  },

  hooks: {
    afterGenerate: 'prettier --write "sdk/**/*.ts"',
  },

  versionSync: {
    enabled: true,
    source: 'package.json', // 或直接写死 semver，如 '1.2.3'
  },

  mock: {
    enabled: true,
    provider: 'msw',
  },
} satisfies SdkGenConfig;

支持 .ts、.js、.mjs、.cjs、.json 配置文件（通过 jiti 加载）。 CLI 参数会覆盖配置文件中的值。

程序化 API

import {
  loadConfig,
  generateSdk,
  validateSdk,
  isValidationPassing,
} from '@huchenghe/sdk-gen-core';

const config = await loadConfig('sdk.config.ts', { version: '1.2.3' });

await generateSdk({ config }); // 执行完整管线

const results = await validateSdk({ config });
console.log(isValidationPassing(results)); // true / false

生成的 SDK 结构

sdk/
├── src/
│   ├── client.ts        # Axios 包装：拦截器、token、单例 SdkClient
│   ├── api-registry.ts  # 自动发现的 API 注册表（createApiRegistry）
│   ├── mock.ts          # MSW：setupMocks / createMockHandler / createMockClient
│   ├── version.ts       # SDK_VERSION + API_BASE_PATH（版本同步）
│   └── index.ts         # 入口 —— 统一导出 API + models
├── generated/           # OpenAPI Generator 原始输出（apis/ + models/）
├── tests/sdk.test.ts    # 冒烟测试
├── package.json         # 独立可发布的 npm 包
├── tsconfig.json
└── README.md

import { SdkClient, SDK_VERSION } from '@my-org/api-sdk';

const client = SdkClient.getInstance({
  baseURL: 'https://api.example.com',
  token: localStorage.getItem('token'),
});

const { data } = await client.apis.userAuth.getUser({ userId: 42 });

扩展生成器

import { registerGenerator, type Generator } from '@huchenghe/sdk-gen-core';

const myGenerator: Generator = {
  name: 'typescript-fetch',
  async generate(ctx) {
    /* 把你的生成器产物写入 ctx.generatedDir */
    return { generatedDir: ctx.generatedDir, files: [] };
  },
};

registerGenerator(myGenerator);

GitHub 发布

把生成的 SDK 变成独立的 GitHub 仓库并从这里发布 —— 通过 GitHub Packages 可以免费 替代 npm 的付费私有组织方案（私有 SDK 给团队用，公共仓库还能对外开放）。

在 sdk.config.ts 中启用（或 sdk-gen generate --github）：

github: {
  enabled: true,
  visibility: 'public',   // 'public' | 'private'
  autoPush: true,         // gh repo create + push（需要 `gh auth login`）
  publish: { npm: true, ghcr: true }, // 两个发布目标（默认）
},
// owner/repo 默认取 npmScope/npmPkgName

generate 会额外：

1. 写入 .github/workflows/sdk-publish.yml（发布 job）；
2. 在 SDK 目录 git init 并做首次提交；
3. 通过 gh CLI 自动创建远程仓库并推送（尽力而为 —— gh 缺失只警告，不阻塞生成）。

推送 tag 即可发布：

git tag v1.2.3 && git push origin v1.2.3             # → npm（需要 NPM_TOKEN secret）
git tag ghcr-v1.2.3 && git push origin ghcr-v1.2.3    # → GitHub Packages（用 GITHUB_TOKEN）

GitHub Packages 免费 —— 私有 SDK 可以只给团队用，公共仓库还能对外开放，完全不需要 npm 付费订阅。生成的 package.json 自带 publishConfig.registry 指向 GitHub Packages， 所以本地 npm publish 默认发到 ghcr；发 npm 的 job 会先删掉它再发布到 npmjs.org。

生成的 SDK 托管在 GitHub 后，使用者怎么安装

SDK 进了 GitHub 仓库后，你的团队（或外部使用者）用下面两种方式之一安装：

# 直接从仓库装 —— 完全不需要任何 npm registry
pnpm add github:<owner>/<repo>#v1.2.3

# 或者从 GitHub Packages 装 —— 先在 .npmrc 里指向 ghcr：
#   @<scope>:registry=https://npm.pkg.github.com/
#   //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
pnpm add <package-name>

GitHub Packages 要求 npm scope 与 GitHub 账号/组织名一致（比如 @huchenghe/api-sdk 只能在名为 huchenghe 的账号下发布到 ghcr）；如果不一致，就改用 git URL 安装或发到 npmjs。生成的 SDK 自带 README 里已经写好了你这个包的准确命令 —— 开启 github 后 generate 一次就能看到。

校验

sdk-gen validate 会检查：swagger 是否存在（paths/schemas 数量）、generated/apis 与 generated/models 是否生成、所有包装层源文件是否齐全、swagger path 数量与 API 文件数量 是否一致、注册表结构、以及入口文件是否泄漏敏感关键字。当你单独校验一个 SDK 目录（无 swagger 文件）时，swagger 相关的检查会优雅地跳过。

开发

pnpm install
pnpm typecheck   # tsc --noEmit
pnpm test        # vitest —— 单元测试 + mock generator 集成测试（无需 Java）
pnpm test:integration  # 真实 openapi-generator 运行（需要 Java 8+ 与网络）
pnpm build       # tsup → dist/

发布

打 tag 触发 release.yml 工作流（需要配置 NPM_TOKEN secret）：

git tag v0.1.0
git push origin v0.1.0

License

MIT