vite-plugin-swagger-typescript-api

基于 unplugin 的插件，构建时自动扫描 Swagger/OpenAPI YAML 文件生成 TypeScript API 客户端。支持 Vite、Rollup、Webpack、Rspack、Nuxt、esbuild、Farms、Astro 等。

安装

npm i vite-plugin-swagger-typescript-api

快速开始

1. 项目根目录创建 yaml/ 文件夹，放入 Swagger YAML 文件
2. 配置插件
3. 自动生成 src/api/ 下的 TypeScript API 代码

配置选项

SwaggerTSApi({
  rootDir?: string           // 扫描根目录，默认 process.cwd()
  outputDir?: string        // 输出目录，默认 'src/api'
  generateClient?: boolean  // 生成请求函数，默认 true
  httpClient?: 'fetch' | 'axios'  // HTTP 客户端，默认 'fetch'
  baseURL?: string          // API 基础 URL（生成 request.ts）
  watch?: boolean           // 监听文件变化，默认 true
  moduleNameFormat?: 'kebab' | 'camel' | 'pascal'  // 模块名格式，默认 'kebab'
})

构建工具集成

Vite

// vite.config.ts
import SwaggerTSApi from 'vite-plugin-swagger-typescript-api'

export default {
  plugins: [SwaggerTSApi({ outputDir: 'src/api' })]
}

Rollup

import SwaggerTSApi from 'vite-plugin-swagger-typescript-api/rollup'

export default { plugins: [SwaggerTSApi({ outputDir: 'src/api' })] }

Webpack

const SwaggerTSApi = require('vite-plugin-swagger-typescript-api/webpack')

module.exports = {
  plugins: [new SwaggerTSApi({ outputDir: 'src/api' })]
}

Rspack

import SwaggerTSApi from 'vite-plugin-swagger-typescript-api/rspack'

export default { plugins: [SwaggerTSApi({ outputDir: 'src/api' })] }

Nuxt

// nuxt.config.ts
export default {
  modules: ['vite-plugin-swagger-typescript-api/nuxt'],
  swaggerTsApi: { outputDir: 'src/api' }
}

Vue CLI

// vue.config.js
module.exports = {
  configureWebpack: {
    plugins: [new (require('vite-plugin-swagger-typescript-api/webpack'))({})]
  }
}

esbuild

import { build } from 'esbuild'
import SwaggerTSApi from 'vite-plugin-swagger-typescript-api/esbuild'

build({ plugins: [SwaggerTSApi({})] })

Farm

import SwaggerTSApi from 'vite-plugin-swagger-typescript-api/farm'

export default { plugins: [SwaggerTSApi({})] }

Astro

// astro.config.mjs
import SwaggerTSApi from 'vite-plugin-swagger-typescript-api'

export default {
  vite: { plugins: [SwaggerTSApi({ outputDir: 'src/api' })] }
}

部署项目

构建

# 开发环境（带 watch 模式，自动重新生成 API）
npm run dev

# 生产构建
npm run build

生成产物

插件在 构建时 生成 API 代码到 outputDir，生成的代码是普通 TypeScript，无需特殊处理：

# 构建后 src/api/ 目录结构示例
src/api/
├── index.ts              # 统一入口
├── request.ts            # HTTP 客户端（配置 baseURL 时生成）
├── user/                 # 根据 yaml/user.yaml 生成
│   ├── Api.ts
│   ├── index.ts
│   └── example.ts
└── product/
    ├── Api.ts
    ├── index.ts
    └── example.ts

提交到 Git

建议将 outputDir（如 src/api）一起提交，因为：

• API 代码由 YAML 驱动，提交后可追溯
• 团队成员无需运行插件即可开发
• 构建时即使 YAML 解析失败也有可用代码

如果只想在构建时生成，可将 src/api 加入 .gitignore：

# 取消注释如果你不希望提交生成的 API 代码
# src/api/

CI/CD 注意事项

确保 CI 环境安装依赖后执行构建命令：

# .github/workflows/deploy.yml 示例
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- run: pnpm install
- run: pnpm run build  # 插件在此阶段生成 API 代码

项目架构

src/
├── index.ts           # 插件入口
├── types.ts          # 类型定义
├── utils.ts          # 工具函数
├── core/             # 核心模块
│   ├── constants.ts  # 常量
│   ├── plugin.ts     # unplugin 工厂
│   ├── scanner.ts    # 扫描协调
│   └── generator.ts  # API 生成
└── generators/       # 代码生成器
    ├── example.ts
    ├── module-index.ts
    ├── entry-index.ts
    └── request.ts