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。

修改历史说明

• 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 上，无法正常使用的问题（亲测，可用了）

• 0.1.1 -> 0.1.2
  1、修改 API 引用 model 的路劲，在添加服务名称后不匹配问题
  2、添加排除路径，设置不生成的接口路径（因为，有时一个服务中，既有 PC 端接口，又有移动端接口，PC 不想生成移动的，移动不想生成 PC 的
  

• 0.1.2 -> 0.1.4
  1、适配多个模式的 swagger 工具
  

• 0.1.4 -> 0.1.5
  1、修改没有属性的实体报错问题
  

• 0.1.5 -> 0.1.7
  1、修改没有属性的实体报错问题
  2、Hooks 中删除无用的代码
  

• 0.1.7 -> 0.1.8
  1、修改接口的 responses 没有绑定返回对象的问题
  2、添加配置属性【onlyPath】，只生成某个路径，这个跟【excludeRoute】属性是互斥的
  

• 0.1.8 -> 0.1.9
  1、完善配置文件 swagger2ts.json 中的四属性：commonResponse、pageResponse、listResponse、utilsPath；utilsPath 描述的是接口返回对象的通用描述文件地址；commonResponse、pageResponse、listResponse 三个描述的是三种类型的返回结构，三个文件在 utilsPath 描述的文件中。
  2、修改在同一个文件中，实体对象存在重复的问题
  3、修改 api、apiHook 与 models 之间的引用错误问题
  

• 0.1.9 -> 0.2.0
  1、添加对返回结构 Page结构的识别
  

• 0.2.0 -> 0.2.1
  1、修改 Get 接口的生成
  

• 0.2.2 -> 0.2.3
  1、接口返回类型不是标准的 list 等格式时，接口没有返回类型问题修改
  

• 0.2.3 -> 0.2.4
  1、接口函数，参数为{}的问题修改
  

• 0.2.4 -> 0.2.5
  1、处理自定义的返回类型的生成和绑定
  

• 0.2.5 -> 0.2.7
  1、支持生成所有类型的请求实体和返回嵌套实体
  

License

Apache-2.0 © gyj