介绍

前段时间，公司定下基调，使用TypeScript进行项目的开发。但是每次跟后端对接，这个模型等翻译实在是枯燥无味，所以就想着工具解决。github上找了一圈，没有那种简单、傻瓜式的工具，所以决定自己写一个。

swagger2Tots

一款基于 swagger 2.0 、typescript 的 代码生成器 ，借助这个软件包，可以生成一个访问 swagger api 对应的 model、api、apiHook。

安装

npm install -g swagger2-to-ts

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

stt --help // 查看相关的说明
stt i // 初始化配置文件
stt init // 初始化配置文件
stt u http://XXX/swagger-ui.html  // 把url对应的swagger生成相关的model、api、apiHook。
stt url http://XXX/swagger-ui.html // 把url对应的swagger生成相关的model、api、apiHook。

工具介绍

• 目前只支持 swagger 2.0
• 可以选择生成相关的文件，包含 model、api、apiHook
• 生成的文件是 ts 格式的。（目前支持 ts 格式，所以配置文件中【fileType】修改无效）
• 所有文件会根据 swagger 提供的说明描述，添加相关描述

生成代码 demo：

// -- model样例
import { itemResult } from '/@/models/httpResult'

// 查询准入评级明细
export type AdmittanceRatingDto = {
  admittanceId: string, // 准入评级id
  admittanceName: string, // 准入评级名称
  description: string, // 准入评级描述
  online: boolean, // 是否上线
  policyIds: Array<string>, // 策略id列表
  scopes: object, // 适用范围
  status: string, // 可用状态
  tags: Array<string>, // 标签
}
export type resultAdmittanceRatingDtoInfo = Promise<
  itemResult<AdmittanceRatingDto>
>

// -- API样例
import { resultAdmittanceRatingDtoIte } from '/@/entitys/admittance'
import { http } from '/@/utils/http'

export const DOMAIN = ''

/**
 * 查询准入评级明细
 * @param data
 * @returns resultAdmittanceRatingDtoItem
 */
export const qryAdmittanceRatingDetail = (data: {
  admittanceId: string,
}): resultAdmittanceRatingDtoItem => {
  return http.request(
    'get',
    DOMAIN +
      '/admin/api/admittance/rating/detail' +
      '?admittanceId=' +
      data.admittanceId,
    {}
  )
}

// -- apiHooks样例

import { resultAdmittanceRatingDtoItem } from '/@/entitys/admittance'
import { qryAdmittanceRatingDetail } from '/@/api/admittance'
import { errorMessage } from '/@/utils/message/index'

/**
 * 查询准入评级明细
 * @param data
 * @returns Promise<resultAdmittanceRatingDtoItem>
 */
export const useQryAdmittanceRatingDetail = async (data: {
  admittanceId: string,
}): Promise<resultAdmittanceRatingDtoItem> => {
  try {
    const result = await qryAdmittanceRatingDetail(data)
    if (result.resultCode.toUpperCase() != 'SUCCESS') {
      errorMessage('查询准入评级明细失败，原因：' + result.errorCodeDes)
      return null
    } else {
      return result
    }
  } catch (e) {
    errorMessage('查询准入评级明细失败，信息：' + e.message)
    return null
  }
}

说明

• 可以看到 model、api、apiHook 这三者之间的关系，在生成代码的时候，自动已经做好关联

设计的初衷说明

• 再设计的时候考虑到后端给出的 swagger 中可能包含多个 control，基于对象的概念，所以设计根据 paths 去动态匹配相关的 control 名称，从而生成不同对象的 model、api、apiHook。具体可以查看文件【swagger2ts.json】里面的 pathRoute。
• pathRoute 中，匹配时根据排列顺序进行的，一旦前面的匹配到后，则不在匹配。所以使用的时候，需要配置不同的匹配字符和顺序来控制生成不同的 control 对象。如接口路径是： /admin/api/policy/create，那么使用/admin/去做匹配，匹配到的 control 名称为 api，如果使用/admin/api/去匹配，则配到的 control 名称为 policy。

使用

使用npm 全局安装：npm install -g swagger2-to-ts

项目源码目前没有开源，有需要的可以评论去留言。

后端服务的注解

如下图：

• title：服务的英文，必须用英文，如：influence-manage
• description：服务的中文名称，必须是中文，如：达人运营服务

后端实体模型注解

如下图：

• @ApiModel：实体描述，必须以"description='XXXX'"为准。

修改历史说明

• 0.0.5 -> 0.0.6 1、根据不同的 swagger,生成对应服务名称的文件夹，从而规避服务之间，重名导致的冲突问题 2、model 生成模板修改，使用 jsdoc 注释，从而实现感知 3、api 接口调用添加 config，从而实现调用者传入 headers 等自定义信息 4、修改再 mac 系统或者 Linux 系统中，工具报错问题

• 0.0.6 -> 0.0.7 1、服务名称根据 info 中的 title 去生成

• 0.0.8 -> 0.0.9 1、mac端没有盘符，导致创建文件夹报错

• 0.0.9 -> 0.1.1 1、处理在mac上，无法正常使用的问题（亲测，可用了）