哈嘍，我是樹醬。去年中旬的時候寫過一篇關於如何更好管理 Api 介面。最近有朋友問我，我們都是根據Swagger文件，然後通過“閱讀”swagger文件中每個微服務包含的CRUD(增刪查改)等API，再通過“手動”擼出各種service檔案，以此達到封裝的結果。但是這樣會暴露一些問題，如下?
- 如果介面發生變更，比如介面從v1遷移到v2版本，那需要進行大量的改造
- 每增加一個專案，我都是需要封裝一套service，重複造輪子不亦樂乎？
- 團隊加入新成員，編寫重複的介面封裝等
那有什麼辦法可以解決上述的問題？
方法是有的，本質上通過程式自動化去生成各種service檔案，解放雙手。那具體怎麼做呢？我們可以通過解析swagger介面文件的結構
1.什麼是 Swagger / OpenAPI ？
在聊解析文件之前，我們首先需要先了解一下 OpenAPI ?
OpenAPI規範，也稱作OAS，是一種API文件標準
通過 OpenAPI 規範來定義您的 API，您就可以用文件生成工具來展示您的 API，甚至可以使用程式碼生成工具來自動生成各種程式語言的伺服器端和客戶端的程式碼。
? 啊樂同學：那openAPI與swagger之間有是什麼關係？
OpenAPI 始於 Swagger 規範，Swagger 規範已於2015 年捐贈給 Linux 基金會後改名為 OpenAPI，並定義最新的規範為 OpenAPI 3.0
本質上你可以理解為前者是規範，後者則是實現規範的工具 ?
- OpenAPI = 規範
- Swagger = 實現規範的工具
? 啊樂同學：那麼一個通過OpenAPI規範實現的物件是什麼樣子的呢？
具體主要包括以下這些欄位資訊（指的是OpenAPI 3.0）
如果你想實時預覽OpenAPI線上編輯的效果，可以嘗試使用 Swagger Editor
? 啊呆同學：我看有兩種規範，OAS2與OAS3，這兩種有什麼區別呢？
OAS2是Swagger2的簡稱，上文提到，自 Swagger 規範捐獻給linux之後，將Swagger規範重新命名為OpenAPI規範，就是我們提到的OAS3。下圖是兩者的區分?
推薦閱讀：
2.如何解析 Swagger / OpenAPI ？
梳理完OpenAPI規範結構，接下來我們就需要通過解析OpenApi文件結構來生成我們的service檔案
我在社群找到目前的兩種解決方式 ?
2.1 @umijs/plugin-openapi外掛
umijs封裝了一個openapi外掛，通過輸入一個 openapi 的規範檔案，就可以完成自動化建立service。
這個規範檔案我們在通過swagger-ui的介面中可以獲取
然後把這個複製swagger的url到openapi的配置中（schemaPath引數），可以參考下圖?
然後執行命令列就可以自動生成以下目錄結構serves
這裡以寵物商店的DEMO API 文件為例，看下生成的介面封裝成什麼樣子
同時在serves中我們也會生成 typings.d.ts 檔案，包含了openapi中的定義
目前該工具的劣勢在於，重度繫結了umi且對中文支援不友好。如果你覺得不適合內部的技術棧，可以參考該工具的實現思路，然後在它的基礎上自己造輪子
2.2 本地化工具生成
OpenApi社群開源了OpenApi Generator，我們可以通過 OpenAPI Generator，通過提供OpenAPI 規範(上文提到的OAS2和OAS3)來自動生成 API 客戶端庫、文件及配置。比如我們前端依賴axios作為請求庫，那麼我們可以通過指定型別來生成ts+axios的請求相關的程式碼
具體使用請查閱 ? github - openapi-generator
如果你是前端並且對java並不熟悉的童鞋，直接使用會收到技術棧限制，因為它提供的是一個JAR包，雖然也有提供cli工具，但是隻支援yml格式解析
那麼有沒有更編輯的方式，可以不依賴環境去使用呢？
這裡提供一個工具，方便你直接使用: Apifox
Apifox不僅支援mock功能和介面除錯，我發現還有個程式碼生成功能，程式碼生成引擎使用的也就是我們提到的openapi-generator，可以根據介面/模型定義，自動生成各種語言/框架（如 TypeScript、Java、Go、Swift 等130 種語言及框架）的業務程式碼，比如介面請求程式碼
上圖是Apifox的生成程式碼的介面，這裡以TypeScript語言+axios請求庫為例，我們還可以選擇我們匯出的程式碼包含的內容，比如只需要僅介面程式碼或僅模型等
3.最後
如果你有更好的實現方式，也可以在評論區留言，也可以加我微信，我們一起喝茶? 討論