swagger2-to-ts2

0.2.10 • Public • Published

swagger2-to-ts2

一款基于 swagger 2.0 、typescript 的 代码生成器 ,借助这个软件包,可以生成一个访问 swagger api 对应的 model、api、apiHook。
目前没有发布该工具库。

安装

npm install -g swagger2-to-ts2

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

stt2 --help // 查看相关的说明
stt2 i // 初始化配置文件
stt2 init // 初始化配置文件
stt2 u http://XXX/swagger-ui.html  // 把url对应的swagger生成相关的model、api、apiHook。
stt2 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.1.0
    1、完成 rollup 的打包配置

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

  • 0.1.3
    1、适配多个模式的 swagger 工具

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

  • 0.1.5
    1、实体没有属性导致的报错问题修改

  • 0.1.6
    1、hoooks 中的无用代码删除

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

  • 0.1.7 -> 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.6
    1、处理自定义的返回类型的生成和绑定

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

License

Apache-2.0 © gyj

Package Sidebar

Install

npm i swagger2-to-ts2

Weekly Downloads

1

Version

0.2.10

License

MIT

Unpacked Size

2.29 MB

Total Files

13

Last publish

Collaborators

  • kimi_gyj