一、背景

商業側的業務比較復雜，B端項目中含有大量常量類的類型判斷，且因歷史原因，很多常量值前端無法直接知其含義，這既不利于新人的上手，也不利于項目的維護。

在開發協作上，前后端的API溝通，大都通過配置swagger api來進行，要不就是口口相傳或者通過寫info文檔來定義結構、入參及出參，這種協作方式不僅溝通成本高，且前端缺少能主動感知后端API變更的手段。

同時，為了提高項目的可維護性，組內推動前端項目TS工程化，在改造過程中，也會因為業務迭代，需要創建新的項目，而新項目TS工程化的過程，不僅需要自定義大量的類型，也需要定義后端API類型參數，如果全部通過手動敲，代價太大，不僅很容易出錯，也會影響業務的開發效率。

因此，為了提升開發協作效率，增加前端主動感知API的能力，提升項目的可維護性和開發效率，開發實現了TS自動化生成工具。

二、核心功能

1. 自動生成api函數體結構
2. 自動化生成api interface
3. 自動生成本地mock file
4. 支持自定義模版輸出改造
5. 支持駝峰與下劃線轉換輸出
6. 支持自定義header改造
7. 同時支持swagger api v2和v3版本

三、轉換原理

swagger api doc的文檔結構

圖片

關鍵屬性拆分：

圖片

注：Template Function可根據實際情況進行覆蓋，默認是商業側的模版輸出格式。

四、項目接入

工具地址：（Package - @bilibili-business/ad-swagger-fe）

接入步驟：

1.安裝

npm install @bilibili-business/ad-swagger-fe --registry=http://registry.npm.bilibili.co

2.配置模版文件，在項目根目錄下新建swagger.config.js文件（目錄按需）

3.可將示例代碼（下方文檔中）可以直接copy到swagger.config.js文件中

4.替換修改代碼中的source地址，將其替換成目標swagger doc地址

5.命令行中執行：node ./swagger.config.js

6.項目中的src目錄下，會多出一個swagger文件夾，即為生成的目標文件

7.可以根據生成的內容，調整工具參數，包括header

模版示例代碼

圖片

五、項目實踐

目前該工具已在商業前端項目中推廣并廣泛使用，商業側整體接入率85%， 帶貨項目接入率100%。

生成的API函數和TS interface 可直接使用，無需手動編碼，業務開發效率提升1pd。

舉例：后端API接口數1556個

圖片

通過工具生成的代碼

• 生成的API實例

圖片

• 生成的Interface

圖片

• 在項目中直接使用

圖片

本期作者

楊雨浩嗶哩嗶哩資深開發工程師