前因

因为公司项目使用了TypeScript，每次跟后端同事联调接口的时候都得去翻Swagger接口文档，写请求函数和函数的参数类型、返回值，要不就把文档中的示例值复制到json2ts网站中生成TypeScript类型。不管哪种方式都很耗时间耗精力。所以慢慢的就全部使用any类型了🤣，最后就变成了 anyscript 。这样有个很烦人的问题，就是后端某些接口参数改了，你还得找到调用这个请求函数的地方，去修改原来的参数。要不就是接口地址变了、参数类型变了......

然后我就想到像Apifox这种接口测试工具不是可以导入Swagger吗，它可以自动生成数据类型文件，马上去它的官网查有没有开放API可让我调用🫣。结果非常的Amazing！并没有......

然后啊，我啪的一下就站起来了。别人能解析为什么我不能解析？难不成他有三头六臂，而我是一头......🤐

说干就干，拿到后端Swagger文档的json文件开始看有哪些字段，大概的逻辑是什么。

结果非常的Amazing啊，json文件里有个definitions字段，这个字段是干什么的呢？来看看官方文档

一个对象，用于保存由操作生成和使用的数据类型。--百度翻译

咳咳，后面的同学，头抬起来。

什么是操作，一个接口就是一个操作。那么生成和使用就很好理解了，分别是接口返回值和接口需要的参数。

咱们再看一眼这个definitions里面到底长啥样：

{
    "definitions":{
         "BarAreaEnableCmd":{
             "type":"object",
             "required":[
                "enableStatus",
                "id"
             ],
             "properties":{
                "enableStatus":{
                   "type":"boolean",
                   "description":"启用停用"
                },
                "id":{
                   "type":"integer",
                   "format":"int64",
                   "description":"ID"
                }
             },
             "title":"BarAreaEnableCmd",
             "description":"区域启用停用"
        }
    }
}

解读一下：在definitions中有个名为BarAreaEnableCmd的对象，其中type键的值是object、required键的值是["enableStatus","id"],properties对象中包含了两个名为enableStatus和id的对象，其中enableStatus对象的type是boolean，description是"启用停用",id对象的type是integer，format是int64，description是"ID"。

再放一张使用这个数据类型的接口截图：

相信聪明的同学看到这里应该就明白了，这是怎么回事儿。如果要写这个接口的interface的话，应该是这样：

// 区域启用停用
export interface BarAreaEnableCmd {
    // 启用停用
    enableStatus:boolean;
    // ID
    id:number;
}

咱就说这几个东西不是一模一样也是十分相似吧。最显眼的差别应该是上面的id是integer，而interface里面的是number，这就是我们要注意的地方。swagger数据类型的字段的类型放在这里了。

思路

众所周知，JSON.parse()可以将一个json对象转化成js对象，Object.keys()可以获取一个由对象键名组成的数组，使用正则^[a-zA-Z]+$可以匹配纯英文的字符串。

有了这些条件，我们就可开始干活了。

首先是从后端的swagger文档地址获取json：

  async function getJson(url: string) {
    const response = await fetch(url);
    return await response.json();
  }

然后是获取json中有效的definitions，什么是有效的，就是字段名是纯英文的。为什么要是纯英文的，那是因为TypeScript的interface只能使用英文名🤣。对于不是纯英文的，就只能使用any。所以说，咱们还得看后端大佬的脸色😒

function isEnglish(str: string) {
    return /^[a-zA-Z]+$/.test(str);
}
  
function getDefinitions(json: any) {
    let result: any[] = [];
        Object.keys(json.definitions).forEach(key => {
            if (isEnglish(key)) {
                result.push(json.definitions[key])
            }
        })
    return result
}

接下来就是重点了，咱们要根据definitions来生成Typescript的interface。

首先是一些辅助函数：

/**
* 生成注释
* @param text 描述信息
* @returns 
*/
function genComments(text: string) {
return `
/**
* ${text}
*/
`
}

const type2JsType: any = {
    integer: 'number',
}

/**
* 生成单条类型
* @param property 键名
* @param type 键类型
* @param required 是否必须
* @returns `\t${property}${required ? '' : '?'}: ${type2JsType[type] ?? type};`
*/
function genType(property: string, type: string, required: boolean) {
    return `\t${property}${required ? '' : '?'}: ${type2JsType[type] ?? type};`
}

接下来就是重头戏了，认真看：

interface DTO {
  type: string,
  properties: {
    [key: string]: {
      type: string,
      enum?: string[],
      description: string,
      items?: {
        type?: string,
        originalRef?: string
      }
    }
  },
  title: string,
  description: string,
  required: string[]
}

/**
* 生成interface
* @param json DTO类型定义
*/
function genInterface(json: DTO) {
// 生成初始的字符串
let string = `
\n
/**
 * ${json.description}
*/
export interface ${json.title} {
`
    // 拿到所有的properties
    let properties = Object.keys(json.properties ?? {})
    // 如果有
    if (properties.length) {
      // 循环操作每一个property
      properties.forEach(property => {
        // 拿到每一个property的description和type
        const { description, type } = json.properties[property]
        // 如果有description就生成注释再拼接，没有就加个换行
        string += !!description ? genComments(json.properties[property].description) : "\n";
        
        // 如果存在枚举值
        if (json.properties[property].enum) {
        // 对枚举值加上单引号再join成联合类型然后生成单条类型再拼接
          string += genType(property, json.properties[property].enum?.map(item => `'${item}'`).join('|') ?? 'any', json.required ? json.required.includes(property) : false)
          // 如果是数组
        } else if (type === 'array') {
        // 先定义一个空的类型
          let newType = ''
          // 因为是数组，那么肯定有个字段是items，但是items中可能有type也可能是originalRef，前者适用于基本类型，后者是引用的其他复杂数据类型。二者必有其一
          if (json.properties[property].items!.type) {
            // 因为type2JsType中只定义了integer到number的映射，其实应该都写出来，就不用??了
            newType = `${type2JsType[json.properties[property].items!.type!] ?? json.properties[property].items?.type}[]`
            // 处理没有type的情况
          } else if (json.properties[property].items?.originalRef) {
             // 看这个引用类型是不是纯英文，是就用它不是就用any
            newType = isEnglish(json.properties[property].items?.originalRef ?? "") ? json.properties[property].items?.originalRef!+"[]" : "any[]"
          }
          // 给字符串拼接类型，required中会包含必有的property，所以要判断一下
          string += genType(property, newType, json.required ? json.required.includes(property) : false)
        } else {
        // 如果又不是枚举值，又不是数组，那就是普通类型，直接生成一下然后拼接。
        // 其实可能是object，但是没找到。
          string += genType(property, type, json.required ? json.required.includes(property) : false)
        }
      })
    }
    // 最后加上 "}"
    string += "\n}";
    // 生成完毕
    return string
  }

这一块总的来说就是根据properties中的字段来生成ts类型。

最后就是使用nodejs的fs来操作文件，将内容写入到文件中

import fs from "node:fs";

let fileName = "index.d.ts"
const filepath = `存储文件的目录`

// 如果目录不存在，就先创建目录
if (!fs.existsSync(filepath)) {
    fs.mkdirSync(filepath, { recursive: true })
} else {
    //如果目录存在就把文件截断，相当于清空
    fs.truncateSync(filepath + "/" + fileName, 0)
}
// 拿到swagger的JSON
let json = await getJson("swagger的json文档地址")

const definitions = getDefinitions(json);

definitions.forEach(definition => {
    const _interface = genInterface(definition);
    // 向文件后面追加内容
    fs.appendFileSync(filepath + '/' + fileName, _interface, {})
})

大功告成，哈哈哈哈！ 不出意外的话，运行代码后会在你设置的目录下面生成一个index.d.ts文件，里面包含了很多的export interface，你可以在需要的地方从这里导入。✌️

示例：

import {SomeInterface} from "index.d.ts";

export function someAPI():SomeInterface{
    // 请求函数逻辑
}

运行时间，对于500多个definitions的文档，整个过程耗时~500ms

结语

当我写完代码测试后，发现运行结果确实按照我的预期。但是有个不可抗拒的因素，就是对于中文或者有符号的definitions无能为力，这一点只能乞求后端大佬不要随心所欲。🥲

因为自己比较菜，不会打包，随后用rust重写了一下，已经发布了npm包，swagger2ts-rust-cli，安装后在package.json的script中添加命令

{
"script":{
    "gen-ts":"swagger2ts --url <swagger文档的json地址> --outdir <输出的文件夹，默认是api> --filename <文件名，默认是index.d.ts>"
    }
}

然后执行

npm run gen-ts
// or
yarn gen-ts

相同的文档数据，rust要比js快100ms左右。✌️

rust代码在这里

重点说明一下：

此代码使用的swagger文档是OAS2.0，也就是常说的swagger，暂时不支持3.0版本也就是openapi生成的文档 。

如何区分：swagger的文档中有个swagger字段，值是2.0，openapi的文档中是openapi：3.0.0。

但是别急，对于openapi文档的支持正在进行中。

人，总是很难满足的......

我在想，TMD interface都生成了还要我自己导入？还有王法吗？还有faaaaaaaaaaaa~律吗？

所以接下来的计划就是：

1. 支持openapi
2. 根据传入的请求函数模板分模块生成请求函数
3. 可选的只生成interface或加上请求函数一起生成
4. 可选的生成部分模块的请求函数
5. 可选的生成部分模块所使用的interface

喜欢的话，请多多的为我star吧❤️