sw2ts-generate

sw2ts-generate

根据 Swagger / OpenAPI 文档自动生成 TypeScript 或 JavaScript 请求代码与类型声明。

• 支持 JSON / YAML 本地文件或在线 URL
• 生成 TypeScript 接口声明（.d.ts）+ 请求函数（.ts）
• 可切换 JavaScript 模式（输出 .js）
• 内置 Swagger UI 预览服务（支持多文档挂载）
• 支持配置文件（sw2ts.config.js / serve.config.js）与命令行参数
• 一键导出配置模板（eject 命令）

---

安装

# 全局安装（使用 CLI）
npm install -g sw2ts-generate

# 或本地安装（在 npm scripts 或代码中调用）
npm install --save-dev sw2ts-generate

---

命令行用法

sw2ts gen — 生成代码

sw2ts gen [options] [file]

从本地 JSON/YAML 文件或在线 URL 生成代码。

选项	说明	默认值
--url <url>	从 URL 拉取 Swagger 文档	—
-c, --config <file>	配置文件路径（不传则自动查找 sw2ts.config.js）	—
-d, --dir <path>	输出目录	—
-o, --output <file>	输出文件名	—
-p, --proxy <path>	请求代理前缀	""
-r, --required	所有属性标记为必填	false
-i, --importAPI <url>	生成代码中 request 工具的 import 路径	../utils/request.ts
-id, --operationId <key>	指定 operationId 字段	—
-m, --mode <mode>	生成模式：typescript 或 javascript	typescript
-s, --separate	按 tag 分文件输出（仅针对英文 tag 有效）	false
-t, --tags <items...>	按 swagger tags 过滤，只生成命中的 API（仅针对英文 tag 有效）	[]

示例

# 从在线 URL 生成（强制必填）
sw2ts gen --url https://petstore.swagger.io/v2/swagger.json -r

# 从本地文件生成，指定输出目录
sw2ts gen -o api/index swagger/swagger.json

# 使用配置文件（自动查找 cwd 下的 sw2ts.config.js）
sw2ts gen swagger/swagger.yaml

# 显式指定配置文件
sw2ts gen -c sw2ts.config.js swagger/swagger.yaml

# 按 tags 过滤，只生成 pet 和 user 相关 API
sw2ts gen --url https://petstore.swagger.io/v2/swagger.json -t pet user

# JavaScript 模式
sw2ts gen -m javascript swagger/swagger.yaml

sw2ts serve — 预览 Swagger 文档

sw2ts serve [file] [options]

启动本地 Swagger UI 服务预览 JSON/YAML 文档，支持单文件或多文档挂载。

选项	说明	默认值
--port <port>	服务端口	3600
--path <path>	Swagger UI 挂载路径	/

file 可为文档文件（.json/.yaml）或配置文件（.js）；不传则自动查找 serve.config.js。

# 单文档预览（默认 3600 端口）
sw2ts serve swagger/swagger.yaml

# 指定端口和路径
sw2ts serve swagger/swagger.json --port 8080 --path /docs

# 通过配置文件挂载多个文档（见下方 serve.config.js 说明）
sw2ts serve serve.config.js

# 不传 file，自动加载 cwd 下的 serve.config.js
sw2ts serve

sw2ts eject — 导出配置模板

sw2ts eject <output> [options]

导出配置模板，支持三种类型：

选项	说明	默认值
-t, --type <type>	配置类型：tsconfig / serve / sw2ts	tsconfig
--expand	展开 tsconfig 的 extends（仅 tsconfig 类型）	true

# 导出 tsconfig（基于内置样板，展开 extends 输出自包含配置，可直接 tsc -p 使用）
sw2ts eject tsconfig.json

# 导出 serve 配置模板
sw2ts eject serve.config.js --type serve

# 导出 sw2ts 配置模板
sw2ts eject sw2ts.config.js --type sw2ts

---

配置文件

sw2ts.config.js — 代码生成配置

在项目根目录创建，gen 命令会自动加载（无需 -c）：

// sw2ts.config.js
export default {
  mode: 'typescript', // 生成模式：typescript | javascript
  required: false, // 属性是否必填
  dir: 'example', // 输出目录
  proxy: '/api', // 请求代理前缀
  output: 'api/index.ts', // 输出文件名
  separate: true, // 按 tag 分文件
  operationId: 'operationId', // operationId 字段名
  importAPI: '../utils/request.ts', // 生成代码的 request import 路径
  tags: ['store', 'user', 'pet'], // 按 swagger tags 过滤
};

命令行参数优先级高于配置文件。

serve.config.js — 预览服务配置

在项目根目录创建，serve 命令不传 file 时会自动加载。支持挂载多个文档到不同路径：

// serve.config.js
export default {
  port: 3600, // 服务端口（可选）
  docs: {
    // 文档挂载映射 { [路由路径]: 文档文件路径 }
    '/': 'swagger/swagger.yaml',
    '/admin': 'swagger/admin.json',
  },
  options: { explorer: true }, // swagger-ui 配置（可选）
};

可通过 sw2ts eject serve.config.js --type serve 快速生成模板。

---

代码调用

除了 CLI，也可以在代码中调用：

import sw2ts, {
  Generate2API,
  setConfSw2ts,
  readSchemaFromUrl,
  readSchemaFromFile,
  createTransfer,
  useSwaggerUI,
} from 'sw2ts-generate';

// 设置配置
setConfSw2ts({
  proxy: '/api',
  path: 'src',
  output: 'api/index',
  tags: [],
});

// 方式一：Generate2API 生成代码并直接写入磁盘文件
const schema = await readSchemaFromUrl('https://petstore.swagger.io/v2/swagger.json');
await Generate2API(schema);
// → 磁盘上生成 api/*.ts、types/swagger/*.d.ts 等文件

// 方式二：GenerateContext 只返回代码字符串，不写文件（适合二次处理）
const generate = sw2ts({ proxy: '/api', path: 'src', output: 'index', tags: [] });
const result = await generate(schema);
console.log(result.request); // string，请求函数代码
console.log(result.definitions); // string，类型声明代码
// → 磁盘上没有新文件，代码全在 result 变量里

导出的 API

函数	说明
Generate2API(data, file?)	生成代码并写入磁盘文件
GenerateContext(config?)	返回代码字符串，不写文件（适合二次处理）
setConfSw2ts(config)	设置全局配置
readSchemaFromUrl(url)	从 URL 读取 Swagger 文档
readSchemaFromFile(file)	从本地文件读取 Swagger 文档
createTransfer(options?)	创建 TS→JS 转译器
useSwaggerUI(file, port, path)	启动 Swagger UI 预览服务

---

代码格式化

生成的代码会通过 prettier-eslint 格式化。可在项目根目录创建配置文件自定义：

// .eslintrc.js
module.exports = {
  extends: ['standard'],
  rules: {
    quotes: ['error', 'single'],
    semi: ['error', 'always'],
  },
};

// .prettierrc.js
module.exports = {
  printWidth: 120,
  tabWidth: 2,
  useTabs: false,
  semi: false,
  singleQuote: true,
};

---

生成示例

生成的代码风格：

// api/pet.ts
import API, { RequestConfig } from '../utils/request.ts';

/**
 * Add a new pet to the store
 * @param {Pet} payload Pet object that needs to be added to the store
 * @returns
 */
export function addPet<T = any>(payload: Pet, config?: RequestConfig) {
  return API.post<T>('/pet', payload, config);
}

/**
 * This can only be done by the logged in user.
 * @param {string} username The name that needs to be deleted
 * @returns
 */
export function deleteUser<T = any>(username: string, config?: RequestConfig) {
  return API.delete<T>(`/api/user/${username}`, undefined, config);
}

// types/swagger/index.d.ts
declare enum PetStatus {
  pending = 'pending',
  sold = 'sold',
  available = 'available',
}

declare interface Pet {
  id?: number; // int64
  category: any;
  name: string;
  photoUrls: string[];
  tags: Tag[];
  /* pet status in the store */
  status: keyof typeof PetStatus;
}

提示：id 等键名包含 id 的属性统一标记为可选（无法设置有效默认值）。body 参数会置于 payload 字段下，请避免参数命名使用 payload。

---

开发

# 安装依赖
npm install

# 打包（两种方案）
npm run build:ts       # tsc 逐文件编译
npm run build:rollup   # rollup 打包（多入口，依赖外置）

# 全局链接（本地调试）
npm link

# 运行测试
npm run test:core

# 预览 Swagger UI
npm run serve

技术栈

• TypeScript 6 + ESM（"type": "module"）
• Commander — CLI 命令解析
• TypeScript Compiler API — AST 生成与转译
• Express + swagger-ui-express — 文档预览

---

License

MIT