一、背景

1、swagger與openapi

??????Swagger：? ? ? ?

????????一種用于描述RESTFUL API的規范，它提供了一種簡單的來描述API的請求和相應參數、錯誤碼、返回數據類型等信息，是開發者可以方便了解API使用方式。

? ? ? ? ?官網:?https://swagger.io/

?????OpenAPI :

????????始于 Swagger 規范，Swagger 規范已于 2015 年捐贈給 Linux 基金會后改名為 OpenAPI，并定義最新的規范為 OpenAPI 3.0。
????????OpenAPI 規范（OAS）是一種通用的、和編程語言無關的 API 描述規范，使人類和計算機都可以發現和理解服務的功能，而無需訪問源代碼、文檔或針對接口進行嗅探。正確定義后，使用者可以使用最少的實現邏輯來理解遠程服務并與之交互。

? ? ? ? 官網:?https://www.openapis.org/

2、API設計優先的理念優勢

? ? ? ? 我們在實際前后端開發的過程中，其實前后端可以并行開發，這樣可以縮短我們的項目工期，提高工作效率。但是，并行工作的前提是，前端知道后端要返回怎么樣的接口數據，后端知道前端需要怎么樣的數據。? 由此， 前后端必須先對API結構進行一個"約定", 約定需要哪些接口、接口的URL、接口的參數、接口的響應等參數，明確后，雙方基于這個接口文檔/接口約定進行開發。

? ? ? ? 但是前端，開發過程中，后端接口還沒做好，怎么對接呢? 此時由于我們已經將接口內容定下來了，所以，此時我們希望有一種工具能夠給一些模擬的數據，前端先針對這些模擬數據進行Mock開發。 最后前后端開發差不多了，直接將API的URL地址改為后端地址，即可完成開發，轉而進行后續測試、部署，極大提高了我們的開發效率。

? ? ? ? 所以一般前后端開發基于OpenAPI的方式，步驟如下:

? ? ? ? 1、API設計優先的理念就是， API是一份前后端開發的”契約”, 前后端先進行數據接口展示和獲取的定義， 也就是定義輸入、正常輸出、異常輸出等情況API的輸入參數、輸出數據格式。 最后雙方再基于API契約進行代碼的實現

? ? ? ? 2、后端根據API接口進行編碼， 前端可以通過Mock程序模擬后端返回(按照API定義的請求、響應數據類型格式)進行隨機數填充

? ? ? ? 3、前后端可以同時基于契約進行并行開發，最后前后端都開發OK了，前端再將API地址從Mock服務器改為測試服務器地址，最后進行調試整合即可

二、API設計的相關工具

? ? ? ? 關于API設計的相關工具可以參考這個站點:?https://openapi.tools/

1、API文檔可視化編輯器(stoplight-studio)

? ? ? ? 如果我們是手動編輯OpenAPI的yaml文檔來生成接口文檔，這個確實效率比較低。人工編寫API的yaml文件，工作量太大，我們可以使用可視化工具對OpenAPI的規范文件進行設計， 最終生成yaml文件. 此時，我們期望有一種可視化工具，通過可視化工具配置，即可完成這個過程。那么這個工具就是stoplight-studio:? ? ?

2、提供給消費者(前端)的Mock服務工具(Prism)

? ? ? ? 前面我們講過，前端不能干等著后端開發完所有接口才能開始進行對接。那么此時，我們前端需要獲取后端的模擬數據，這個Mock工具就是Prism。 它可以根據我們定義的OpenAPI文檔，數據的響應格式、數據類型，返回模擬數據進行填充，這樣就模擬完成前后端對接的工作。 無須等待后端全部完成工作才進行對接。 最后很簡單，當前后端完成后，前端將URL地址換成后端地址即可.

3、提供給生產者(后端)的Code代碼生成工具(OpenAPI Generator)

? ? ? ? 針對后端來說，我們需要根據OpenAPI的URL、參數、響應編寫后端代碼。 此時后端的同學也想提高效率，有沒有根據文檔一鍵生成后端框架代碼的工具呢? 答案是肯定的。 例如Golang的Gin框架，可以通過此工具根據OpenAPI的文檔yaml文件生成route路由代碼，可以提高我們的工作效率。

?三.代碼轉OpenAPI文檔

1、優勢

? ? ? ? 這個工具是我們場景的應用場景。 我們后端在編寫接口的時候，往往都會將這個接口的相關文檔編寫到一個專門記錄這些接口的文檔工具進行記錄。例如Yapi等這些平臺。

? ? ? ? 但是這種方式往往存在一些問題，那就是，每次更新完代碼以后，忘記更新了Yapi的文檔或者漏更新了文檔，導致文檔和最新代碼不一致。

? ? ? ? 此時我們可以借助代碼框架集成swagger、openapi的方式，通過編寫代碼的時候，順帶通過注解的方式，將接口的相關信息寫上，最后在發布項目的時候，自動生成swagger文檔，這樣可以有利于對文檔的實時更新，寫代碼的時候順帶將文檔寫上了，一舉兩得。

2、Gin框架配置Swagger

開源項目地址:?https://github.com/swaggo/gin-swagger

1、安裝依賴

go install github.com/swaggo/swag/cmd/swag@latest
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

2、swag init初始化docs目錄

執行命令: swag init
會生成docs目錄， 目錄里存在swagger api的yaml配置文件以及json相關文件

3、接口添加相關注解

4、main.go配置swagger路由信息

5、swag init 且 運行程序(每次代碼更新，需要swag init生成新的文檔)

四、總結

? ? ? ? 從上文我們可以發現OpenAPI的文檔yaml可以轉換為對應框架的代碼， 對應的框架代碼也可以生成yaml文檔。

? ? ? ? 其實除了上面說的:

????????1、基于文檔契約，前后端可以并行工作

? ? ? ? 2、文檔和代碼可以直接放在一起進行維護，保持文檔與代碼的準確性

? ? ? ? 其實還有一種場景，例如之前你們一直按照這種OpenAPI或者Swagger的方式進行開發，最初使用的是PHP、或者Python， 現在由于業務發展， 需要更加高性能的實現， 轉換為Go或者Java， 那么此時，我們只需要拿到OpenAPI/Swagger的yaml文件，通過工具生成對應Go、Java框架路由代碼， 參數、路由、響應數據格式都一鍵生成，自己再實現接口邏輯即可。

? ? ? ? 不需要自己再慢慢看文檔來從頭到尾實現。