用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

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 211,561评论 6 492
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 90,218评论 3 385
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 157,162评论 0 348
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 56,470评论 1 283
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 65,550评论 6 385
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 49,806评论 1 290
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 38,951评论 3 407
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 37,712评论 0 266
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 44,166评论 1 303
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 36,510评论 2 327
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 38,643评论 1 340
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 34,306评论 4 330
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 39,930评论 3 313
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,745评论 0 21
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,983评论 1 266
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 46,351评论 2 360
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 43,509评论 2 348

推荐阅读更多精彩内容