介紹
隨著前端技術(shù)的不斷進(jìn)步嫂粟,typescript已經(jīng)在前端開發(fā)中也越來越普及勾给。
在前端開發(fā)與后端項(xiàng)目聯(lián)調(diào)的過程中,我們總避免不了要根據(jù)后端的接口文檔(一般是Swagger)來定義前端的API調(diào)用代碼诬烹,同時(shí)要根據(jù)接口文檔中API請(qǐng)求參數(shù)憎妙,返回參數(shù)等定義出前端使用的typescript類型定義,隨著業(yè)務(wù)功能的增大口锭,這項(xiàng)工作也越來越耗費(fèi)前端開發(fā)人員的時(shí)間朦前,然后而這項(xiàng)工作本來是可以通過自動(dòng)化工具去完成的,因?yàn)楹蠖送瑢W(xué)給出的接口文檔中就已經(jīng)包含了請(qǐng)求類型鹃操,方法名稱韭寸,參數(shù)類型,返回值類型等定義荆隘,只需要通過工具依據(jù)固定的規(guī)則轉(zhuǎn)化為前端代碼即可恩伺。
swagger-typescript-api 這個(gè)開源工具包就是幫助我們完成這件事情的,利用它我們可以很方便地生成前端的typescript類型定義以及API調(diào)用代碼椰拒。而且它同時(shí)支持JSON, yaml兩種格式晶渠。
文檔 https://github.com/acacode/swagger-typescript-api
例子 https://github.com/acacode/swagger-typescript-api/tree/master/tests
使用方式
swagger-typescript-api 可以通過命令行的方式直接使用, 也可以在nodejs中引入調(diào)用燃观。
命令行的使用方式
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兩個(gè)配置項(xiàng)褒脯,這代表兩種swagger內(nèi)容獲取方式,二者選其一即可缆毁。個(gè)人推薦url的方式番川,后端swagger定義更新后,我們直接重新運(yùn)行生成命令即可脊框,不用替換swagger內(nèi)容颁督,更加方便一些。modular選項(xiàng)不加的話缚陷,默認(rèn)將所有api接口放在一個(gè)API文件里适篙,可讀性略差往核,加上modular屬性并設(shè)置為true, 可以更具swagger中定義的API模塊箫爷,分別生成單獨(dú)的API類文件,這樣可讀性較高一些聂儒。
定制模版
想要自定義生成的API代碼的話虎锚,可以通過定制模版來實(shí)現(xiàn)。
首先我們可以將 swagger-typescript-api 這個(gè)包下面templates目錄下的默認(rèn)模版給復(fù)制過來衩婚,然后根據(jù)自己的需要進(jìn)行修改窜护。
/templates/default 是單API文件模式的模版
/templates/modular 是多個(gè)API文件模式的模版(需要將配置項(xiàng)modular設(shè)置為true)
/templates/base 是單API模式和多API模式共用的基礎(chǔ)模版
根據(jù)自己的需要,只拷貝需要的目錄和文件即可非春,模版使用了ETA語法柱徙,語法參考 https://eta.js.org/docs/syntax