nswag-ts

📖 介绍

nswag-ts 是一个强大的 VS Code 扩展，能够根据 Swagger/OpenAPI 文档自动生成 TypeScript 客户端调用代码。它支持自定义模板、代码格式化、Mock 数据生成等功能，让前端开发更加高效。

✨ 主要特性

• 🚀 一键生成：根据 Swagger 文档自动生成 TypeScript 接口代码
• 🎨 模板定制：支持自定义 EJS 模板，满足不同项目需求
• 📝 代码格式化：集成 Prettier，自动格式化生成的代码
• 🎭 Mock 数据：自动生成模拟数据，支持自定义格式化规则
• 🔧 灵活配置：支持多 API 配置，可自定义命名规则
• 📊 进度显示：实时显示代码生成进度，支持取消操作
• 📋 日志记录：详细的日志记录，便于调试和问题排查

🛠️ 安装

1. 在 VS Code 中打开扩展面板 (Ctrl+Shift+X 或 Cmd+Shift+X)
2. 搜索 nswag-ts
3. 点击安装

或者直接从 VS Code Marketplace 安装。

🚀 快速开始

第一步：初始化模板

1. 在项目根目录右键
2. 选择 nswag-ts.init 初始化模板
3. 等待模板文件复制完成

这将自动创建 nswag 文件夹，包含配置文件和代码模板。

第二步：配置 API

编辑项目根目录下的 nswag.js 文件：

module.exports = {
  Name: 'nswag-ts',
  Description: '根据swagger文档生成typescript客户端调用代码',
  Apis: [
    {
      SwaggerUrl: 'https://your-api.com/swagger.json', // 接口文档地址（必填）
      ApiBase: 'https://your-api.com/api', // 接口根节点（必填）
      ApiName: 'UserService', // 接口名称（必填）
      OutPath: 'src/api', // 输出目录（可选，默认：src/api/{ApiName}）
      TplPath: 'nswag/template', // 模板路径（可选，默认：内部默认模板）
      Mock: true // 是否启用模拟数据（可选，默认：false）
    }
  ],
  prettier: {
    parser: 'babel-ts',
    singleQuote: true,
    printWidth: 180,
    tabWidth: 2,
    semi: false,
    trailingComma: 'none'
  }
}

第三步：生成代码

1. 选中 nswag.js 配置文件
2. 右键选择 nswag-ts.run 生成代码
3. 等待代码生成完成

⚙️ 配置详解

API 配置参数

代码格式化配置

支持 Prettier 的所有配置选项，参考 Prettier 官方文档：

prettier: {
  parser: 'babel-ts',        // 解析器
  singleQuote: true,         // 使用单引号
  printWidth: 180,           // 行宽
  tabWidth: 2,               // 缩进
  semi: false,               // 不使用分号
  trailingComma: 'none'      // 尾随逗号
}

🎨 模板定制

模板文件说明

• base.ejs.t - 接口调用基类模板，默认使用 axios
• method.ejs.t - 接口函数生成模板
• model.ejs.t - 数据模型生成模板
• mock.ejs.t - Mock 数据调用模板
• mock-method.ejs.t - Mock 数据接口模板

模板辅助函数

在模板中可以使用以下辅助函数：

// 1. 格式化参数对象，获取指定类型的参数
this.getParameter(参数对象, ['query', 'body'], callback)

// 2. 获取指定控制器依赖的模块
this.getTagModels(tag)

// 3. 格式化返回对象
this.getResponses(m.responses)

// 4. 获取全部类型和枚举对象
this.getModelsAndEnums()

// 5. 根据返回对象，生成Mock数据
this.mock(responses, data.Models)

// 6. 获取全部控制器，swagger里面对应tag标签
this.getTags()

自定义格式化函数

支持自定义命名和格式化规则：

{
  // 格式化模块名称（默认：接口名称+Api）
  FormatControllerName: (name) => {
    return name.indexOf('Api') !== -1 ? name : name + 'Api'
  },

  // 格式化接口名称（默认：小驼峰命名）
  FormatMethodName: (name) => {
    if (name === '/' || name === '') return ''
    const fnName = name.substring(name.lastIndexOf('/'))
    return _.camelCase(fnName)
  },

  // 格式化数据模型名称（默认：去除特殊字符）
  FormatModelName: (name) => {
    return name.substring(name.lastIndexOf('/') + 1).replace(/[.,\[\]]/g, '_')
  },

  // 自定义Mock数据格式化
  FormatMock: (val, property, mock) => {
    switch (property.type) {
      case 'string':
        switch (property.name) {
          case 'name': val = '@cname'; break
          case 'email': val = '@email'; break
          case 'mobile': val = '@natural(10000)'; break
          default: val = '@ctitle(10, 20)'; break
        }
        break
      case 'number':
        val = '@integer(0, 100)'
        break
      case 'array':
        mock[property.name + '|20'] = val
        break
    }
    mock[property.name] = val
    return mock
  }
}

📁 项目结构

your-project/
├── nswag/                    # 配置和模板目录
│   ├── nswag.js            # 配置文件
│   └── template/           # 代码模板
│       ├── base.ejs.t      # 基类模板
│       ├── method.ejs.t    # 方法模板
│       ├── model.ejs.t     # 模型模板
│       ├── mock.ejs.t      # Mock模板
│       └── mock-method.ejs.t # Mock方法模板
├── src/
│   └── api/                # 生成的API代码
│       └── UserService/    # 按API名称分类
└── package.json

🔧 高级用法

多 API 配置

支持同时配置多个 API 服务：

Apis: [
  {
    SwaggerUrl: 'https://user-api.com/swagger.json',
    ApiBase: 'https://user-api.com/api',
    ApiName: 'UserService',
    OutPath: 'src/api/user'
  },
  {
    SwaggerUrl: 'https://order-api.com/swagger.json',
    ApiBase: 'https://order-api.com/api',
    ApiName: 'OrderService',
    OutPath: 'src/api/order'
  }
]

条件生成

在模板中使用条件判断：

<% if (this.hasProperty(model, 'required')) { %>
  required: true,
<% } %>

自定义类型映射

// 在模板中处理特殊类型
<% if (property.type === 'integer' && property.format === 'int64') { %>
  type: 'string' // 将 long 类型转换为 string
<% } else { %>
  type: '<%= property.type %>'
<% } %>

🐛 故障排除

常见问题

1. 模板初始化失败

   • 确保在项目根目录执行初始化
   • 检查 VS Code 权限设置

2. 代码生成失败

   • 验证 Swagger 文档地址是否可访问
   • 检查配置文件格式是否正确
   • 查看输出面板的详细错误信息

3. 生成的代码格式不正确

   • 检查 Prettier 配置
   • 确保项目已安装 Prettier 依赖

日志查看

生成的代码会显示在 VS Code 的输出面板中，选择 "nswag-ts" 输出源查看详细日志。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

• 项目地址：https://gitee.com/money-code/nswag-ts-vscode
• 问题反馈：Issues

📄 许可证

本项目采用 MIT 许可证。

🙏 致谢

感谢所有为这个项目做出贡献的开发者！