纯手写一个解析工具 swagger-to-typescript

本文正在参加「金石计划」 随着 TypeScript 使用越来越普遍，根据后端的接口定义，我们需要生成对应的 TypeScript 文件，包括类型定义文件和接口文件。这个纯手工转换的过程重复又机械，因此，我们完全可以将其转换过程通过程序完成，提供劳动生产力 😉 。本文记录了自己使用 node 工具实现的过程包括 js 和 ts 两个版本，当然大家也可以使用第三方包 swagger-typescript-api 去实现哦。文章末尾附源码。

swagger.json

通过浏览器 F12 查看Network 得出：我们平时看到如图的 swagger 生成的文档的数据是 petstore.swagger.io/v2/swagger.… 请求得到的。

swagger.json 中包含了项目所有的类型和接口定义。

接口返回中，

• definitions 是关于项目所有类型的定义
• paths 是所有的接口定义信息
• tags 是所有的 tag 信息，而接口则根据 tag 进行分类。在下面的生成接口定义文件中，我们可以根据 tag 进行划分，将其生成到对应的文件中。
  

更多信息参见：swagger.io/docs/specif…

node

我们需要将转化过程封装成一个函数，通过 Node.js 运行程序，执行方法，得到我们生成的类型文件和接口定义文件。

• 通过 axios 请求 petstore.swagger.io/v2/swagger.… 得到相应的数据
• 通过 fs 文件模块生成类型定义文件和接口文件。

生成定义文件 newTypes.ts

在生成类型定义文件中的一些约定：

• 生成的定义字段统一使用可选类型 ?
• 类型转换规则：

/**
 * 得到 interface 定义字符串
 * @param prop interface 名称
 * @param definition interface 字段信息
 * @returns interface 定义字符串
 */
const getDefinitionType = (prop, definition) => {
  const cleanProp = prop.replace('«', '').replace('»', '')
  let types = `export interface ${cleanProp} {\n`
  const properties = definition.properties
  for(let p in properties){
    const detail = properties[p]
    const cur = getType(detail)

    if(detail.description){
      types += `  /** ${detail.description} */\n`
      types += `  ${p}?: ${cur}\n\n`
    }else{
      types += `  ${p}?: ${cur}\n`
    }
  }
  types += `}\n\n`
  return types
}

根据 tag 生成相应的接口文件

关于请求参数的类型包括：

• query parameters, such as /users?role=admin
• path parameters, such as /users/{id}
• body parameters that describe the body of POST, PUT and PATCH requests (see Describing Request Body)
• header parameters, such as X-MyHeader: Value
• form parameters – a variety of body parameters used to describe the payload of requests with Content-Type of application/x-www-form-urlencoded and multipart/form-data (the latter is typically used for file uploads)

我们主要需要处理 query、path 以及 body 这三种类型：

注意：根据 swagger.io/docs/specif… 文档说明，其中 query 和 path 参数只能是基本类型，而 body 类型的参数可以是基本类型也可以是对象类型，并且 body 只会有一个。

对示例 JSON 解析得到如下文件：

然后我们就可以在项目中使用啦。

源码

源码地址： github.com/YY88Xu/swag…

Node.js 简介
swagger doc