介绍

去年写过一款工具，但是在使用的过程中问题很多（对于swagger不了解）。所以，又新起炉灶，写了这款工具swagger2-tools。

解决的问题：

基本做到了零配置
服务名称为中文的问题
controller文件，生成逻辑问题
API接口名称，重名问题
对于formData的API接口不支持的问题
对于path模式的Parameter不支持问题
...

下面是该工具的说明：

swagger2-tools

该工具支持 swagger-ui 和 Knife4j 的后端接口，转换为 ts 格式的 model、api、apiHook。

工具介绍

目前只支持 swagger 2.0
可以选择生成相关的文件，包含 model、api、apiHook

安装

bash 复制代码

npm install -g swagger2-tools

命令说明

cd 到你的工作目录，执行:

bash 复制代码

s2t --help // 查看命令说明
s2t i // 初始化配置文件(默认可以不做任何配置)
s2t init // 初始化配置文件(默认可以不做任何配置)
s2t u http://XXX/swagger-ui.html  // 把url对应的swagger生成相关的model、api、apiHook
s2t url http://XXX/swagger-ui.html // 把url对应的swagger生成相关的model、api、apiHook

swagger2ts.jsonc(配置文件) 配置说明

默认是可以不做任何修改的

属性	说明	默认值
swaggerVersion	支持的 swagger 版本	"2.0"
includeTags	包含的 Controller。空是所有，配置了就匹配配置内容(swagger-ui 中 Controller 的中文名称或者英文都支持)	[]
excludeTags	排除的 Controller (高优先级)	[]
fileSettings	model 和 Api 生成规则配置(FileSetting 对象)	{}
serverNameSettings	swagger 的服务名称(映射英文名称)	[]
isHttps	是否使用 https 获取 swagger 信息	false

FileSetting 对象说明

属性	说明	默认值
content	生产文件的内容 all:全部 onlyModel:只生成实体	"all"
topDirPath	生产文件夹的路径默认根目录下"src"	"src"
topAlias	api 和 hook 引用对象的前缀别名	"/@"
axiosImportContent	axios 引用文本	"import { http } from '/@/utils/http'"
messageImportContent	errorMessage 函数的引用文本	"import { errorMessage } from '/@/utils/message/index'"
model	接口实体的生成配置(ModelConfig 对象)	{}
api	接口 http 调用配置(ApiConfig 对象)	{}

ModelConfig 对象说明

属性	说明	默认值
dirName	实体生成的文件夹名称默认根目录下"models"	"models"
createMode	生产文件的模式 add:追加 overwrite:覆盖默认是覆盖（目前追加不支持）	"overwrite"

ApiConfig 对象说明

属性	说明	默认值
dirName	实体生成的文件夹名称默认根目录下"apis"	"apis"
createMode	生产文件的模式 add:追加 overwrite:覆盖默认是覆盖（目前追加不支持）	"overwrite"
nameMode	生成接口的名称的模式：operationId 、url	"url"
urlLevel	截取名称的层级默认是 2	2

Model 生成代码 demo

javascript 复制代码

/** 交易统计 POST /pc/statistics/trade */
export type GroupByVO = {
  /* 收款金额 */
  amount: number,
  /* 收款笔数 */
  count: number,
  /* 时间 */
  text: string,
}
/** 交易统计 POST /pc/statistics/trade */
export type TradeStatisticsVO = {
  /* 新增渠道商 */
  agencyAddCount: number,
  /* 活跃渠道商 */
  agencyCount: number,
  /* 新增商户数量 */
  merchantAddCount: number,
  /* 活跃商户数量 */
  merchantCount: number,
  /* 交易图表数据 */
  orderChartList: GroupByVO[],
  /* 退款图表数据 */
  refundChartList: GroupByVO[],
  /* 渠道商top10数据 */
  top10Agencies: Top10Data[],
  /* 商户top10数据 */
  top10Merchants: Top10Data[],
  /* 门店top10数据 */
  top10Stores: Top10Data[],
  /* 渠道商总数 */
  totalAgencyCount: number,
  /* 商户总数量 */
  totalMerchantCount: number,
  /* 收款总金额 */
  totalOrderAmount: number,
  /* 收款总笔数 */
  totalOrderCount: number,
  /* 收款总手续费 */
  totalOrderFeeAmount: number,
  /* 退款金额 */
  totalRefundAmount: number,
  /* 退款总笔数 */
  totalRefundCount: number,
  /* 退款总手续费 */
  totalRefundFeeAmount: number,
}

/** 交易统计 POST /pc/statistics/trade */
export type CommonResponseTradeStatisticsVO = {
  /*  */
  errorCode: string,
  /*  */
  errorCodeDes: string,
  /* 业务对象 */
  item: TradeStatisticsVO,
  /*  */
  resultCode: string,
}

Api 生成代码 demo

javascript 复制代码

import {
  TradeStatisticsRequest,
  CommonResponseTradeStatisticsTop10VO,
  CommonResponseTradeStatisticsVO,
} from '/@/models/ServerName/StatisticsController'
import { http } from '/@/utils/http'

export const DOMAIN = ''

/**
 * 交易统计
 * @returns CommonResponseTradeStatisticsVO
 */
export const statisticsTrade = (
  data: {},
  config?: any
): Promise<CommonResponseTradeStatisticsVO> => {
  return http.request('POST', DOMAIN + '/pc/statistics/trade', {
    data,
    ...config,
  })
}

ApiHook 生成代码 demo

javascript 复制代码

import { CommonResponseTradeStatisticsVO } from '/@/models/ServerName/StatisticsController'
import { statisticsTrade } from '/@/apis/ServerName/StatisticsController'
import { errorMessage } from '/@/utils/message/index'

/**
 * 交易统计
 * @returns CommonResponseTradeStatisticsVO
 */
export const useStatisticsTrade = async (
  config?: any
): Promise<CommonResponseTradeStatisticsVO | undefined> => {
  try {
    const result = await statisticsTrade({}, config)
    if (result.resultCode.toUpperCase() != 'SUCCESS') {
      errorMessage('交易统计操作失败，原因：' + result.errorCodeDes)
      return undefined
    } else {
      return result
    }
  } catch (e) {
    errorMessage('交易统计操作失败，信息：' + e.message)
    return undefined
  }
}

后续

各位小伙伴，如果使用该工具碰到任何问题，都可以在评论里面告知。或者在github里面给我提issue(swagger2-tools)。

一款开源工具swagger2.0转TypeScript，好用的不得了

介绍

swagger2-tools

工具介绍

安装

命令说明

swagger2ts.jsonc(配置文件) 配置说明

FileSetting 对象 说明

ModelConfig 对象 说明

ApiConfig 对象 说明

Model 生成代码 demo

Api 生成代码 demo

ApiHook 生成代码 demo

后续

FileSetting 对象说明

ModelConfig 对象说明

ApiConfig 对象说明