# sw2ts-generate > sw2ts-generate Latest version **1.0.2** (published 2026-08-11) · MIT license · 0 weekly downloads ## Install ```sh npm install sw2ts-generate pnpm add sw2ts-generate yarn add sw2ts-generate bun add sw2ts-generate ``` Provides the command `sw2ts`. ## Health **Score 70/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 1.0.2 | | Published | 2026-08-11 | | First published | 2021-11-24 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 9 | | Unpacked size | 215.6 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | longxiaobaiWJ | | Maintainers | longxiaobai | | Keywords | swagger, typescript, sw2ts, generate, javascript | ## Links - npm: https://www.npmjs.com/package/sw2ts-generate - Repository: https://gitee.com/frontend_site/sw2ts-generate - npm.io page: https://npm.io/package/sw2ts-generate ## Dependencies (9) - [axios](https://npm.io/package/axios.md) ^1.18.1 - [chalk](https://npm.io/package/chalk.md) ^4.1.2 - [express](https://npm.io/package/express.md) ^5.2.1 - [js-yaml](https://npm.io/package/js-yaml.md) ^5.2.1 - [commander](https://npm.io/package/commander.md) ^12.1.0 - [lodash-es](https://npm.io/package/lodash-es.md) ^4.18.1 - [typescript](https://npm.io/package/typescript.md) ^6.0.3 - [prettier-eslint](https://npm.io/package/prettier-eslint.md) ^15.0.1 - [swagger-ui-express](https://npm.io/package/swagger-ui-express.md) ^5.0.1 ## Alternatives - [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads - [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads - [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads - [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads - [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads ## Recent versions - 1.0.2 (latest) — 2026-08-11 - 1.0.2-beta.2 (beta) — 2026-07-29 - 0.2.9 (lpha.0) — 2021-11-24 - 1.0.2-beta.1 — 2026-07-25 - 0.5.9 — 2024-06-10 - 0.5.8 — 2024-06-09 - 0.5.7 — 2024-06-08 - 0.5.6 — 2024-01-30 - 0.5.5 — 2024-01-29 - 0.5.4 — 2024-01-17 - 0.5.3 — 2023-11-06 - 0.5.2 — 2023-08-01 - 0.5.1 — 2023-07-27 - 0.5.0 — 2023-07-12 - 0.4.9 — 2023-07-11 - … 10 more at https://npm.io/package/sw2ts-generate/versions ## README # sw2ts-generate 根据 Swagger / OpenAPI 文档自动生成 TypeScript 或 JavaScript 请求代码与类型声明。 - 📦 支持 JSON / YAML 本地文件或在线 URL - 🎯 生成 TypeScript 接口声明（`.d.ts`）+ 请求函数（`.ts`） - 🔄 可切换 JavaScript 模式（输出 `.js`） - 🚀 内置 Swagger UI 预览服务（支持多文档挂载） - ⚙️ 支持配置文件（`sw2ts.config.js` / `serve.config.js`）与命令行参数 - 📋 一键导出配置模板（`eject` 命令） --- ## 安装 ```sh # 全局安装（使用 CLI） npm install -g sw2ts-generate # 或本地安装（在 npm scripts 或代码中调用） npm install --save-dev sw2ts-generate ``` --- ## 命令行用法 ### `sw2ts gen` — 生成代码 ```sh sw2ts gen [options] [file] ``` 从本地 JSON/YAML 文件或在线 URL 生成代码。 | 选项 | 说明 | 默认值 | | -------------------------- | ------------------------------------------------------------- | --------------------- | | `--url ` | 从 URL 拉取 Swagger 文档 | — | | `-c, --config ` | 配置文件路径（不传则自动查找 `sw2ts.config.js`） | — | | `-d, --dir ` | 输出目录 | — | | `-o, --output ` | 输出文件名 | — | | `-p, --proxy ` | 请求代理前缀 | `""` | | `-r, --required` | 所有属性标记为必填 | `false` | | `-i, --importAPI ` | 生成代码中 request 工具的 import 路径 | `../utils/request.ts` | | `-id, --operationId ` | 指定 operationId 字段 | — | | `-m, --mode ` | 生成模式：`typescript` 或 `javascript` | `typescript` | | `-s, --separate` | 按 tag 分文件输出（仅针对英文 tag 有效） | `false` | | `-t, --tags ` | 按 swagger tags 过滤，只生成命中的 API（仅针对英文 tag 有效） | `[]` | #### 示例 ```sh # 从在线 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 文档 ```sh sw2ts serve [file] [options] ``` 启动本地 Swagger UI 服务预览 JSON/YAML 文档，支持单文件或多文档挂载。 | 选项 | 说明 | 默认值 | | --------------- | ------------------- | ------ | | `--port ` | 服务端口 | `3600` | | `--path ` | Swagger UI 挂载路径 | `/` | `file` 可为文档文件（`.json`/`.yaml`）或配置文件（`.js`）；不传则自动查找 `serve.config.js`。 ```sh # 单文档预览（默认 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` — 导出配置模板 ```sh sw2ts eject [options] ``` 导出配置模板，支持三种类型： | 选项 | 说明 | 默认值 | | ------------------- | -------------------------------------------- | ---------- | | `-t, --type ` | 配置类型：`tsconfig` / `serve` / `sw2ts` | `tsconfig` | | `--expand` | 展开 tsconfig 的 extends（仅 tsconfig 类型） | `true` | ```sh # 导出 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`）： ```js // 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 时会自动加载。支持挂载多个文档到不同路径： ```js // 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，也可以在代码中调用： ```ts 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` 格式化。可在项目根目录创建配置文件自定义： ```js // .eslintrc.js module.exports = { extends: ['standard'], rules: { quotes: ['error', 'single'], semi: ['error', 'always'], }, }; ``` ```js // .prettierrc.js module.exports = { printWidth: 120, tabWidth: 2, useTabs: false, semi: false, singleQuote: true, }; ``` --- ## 生成示例 生成的代码风格： ```ts // 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(payload: Pet, config?: RequestConfig) { return API.post('/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(username: string, config?: RequestConfig) { return API.delete(`/api/user/${username}`, undefined, config); } ``` ```ts // 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`。 --- ## 开发 ```sh # 安装依赖 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 --- _Source: https://npm.io/package/sw2ts-generate · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._