用swagger-typescript-api根据Swagger定义自动生成前端TypeScript类型定义以及API请求代码

介绍

随着前端技术的不断进步，typescript已经在前端开发中也越来越普及。

在前端开发与后端项目联调的过程中，我们总避免不了要根据后端的接口文档(一般是Swagger)来定义前端的API调用代码，同时要根据接口文档中API请求参数，返回参数等定义出前端使用的typescript类型定义，随着业务功能的增大，这项工作也越来越耗费前端开发人员的时间，然后而这项工作本来是可以通过自动化工具去完成的，因为后端同学给出的接口文档中就已经包含了请求类型，方法名称，参数类型，返回值类型等定义，只需要通过工具依据固定的规则转化为前端代码即可。

swagger-typescript-api 这个开源工具包就是帮助我们完成这件事情的，利用它我们可以很方便地生成前端的typescript类型定义以及API调用代码。而且它同时支持JSON, yaml两种格式。

文档 https://github.com/acacode/swagger-typescript-api

例子 https://github.com/acacode/swagger-typescript-api/tree/master/tests

使用方式

swagger-typescript-api 可以通过命令行的方式直接使用， 也可以在nodejs中引入调用。

命令行的使用方式

npx swagger-typescript-api -p ./swagger.json -o ./src -n myApi.ts

nodejs中使用

const { generateApi } = require('swagger-typescript-api');
const path = require('path');
const outputDir = path.resolve(process.cwd(), './src/__generated__');

/* NOTE: all fields are optional expect one of `output`, `url`, `spec` */
generateApi({
  // input: path.resolve(__dirname, "./schemas.json"),
  url: 'http://api.com/swagger.json',
  output: outputDir,
  modular: true,
  templates: path.resolve(__dirname, './templates'),
  axios: true,
  routeTypes: true,
});

在上面代码中可以看到input 和 url两个配置项，这代表两种swagger内容获取方式，二者选其一即可。个人推荐url的方式，后端swagger定义更新后，我们直接重新运行生成命令即可，不用替换swagger内容，更加方便一些。modular选项不加的话，默认将所有api接口放在一个API文件里，可读性略差，加上modular属性并设置为true, 可以更具swagger中定义的API模块，分别生成单独的API类文件，这样可读性较高一些。

定制模版

想要自定义生成的API代码的话，可以通过定制模版来实现。

首先我们可以将 swagger-typescript-api 这个包下面templates目录下的默认模版给复制过来，然后根据自己的需要进行修改。

/templates/default 是单API文件模式的模版

/templates/modular 是多个API文件模式的模版（需要将配置项modular设置为true）

/templates/base 是单API模式和多API模式共用的基础模版

根据自己的需要，只拷贝需要的目录和文件即可，模版使用了ETA语法，语法参考 https://eta.js.org/docs/syntax