對 API 管理的一些思考

前言

目前市場上有不少 API 管理平臺，這種平臺一多，開發團隊在作選型時 就須要花更多的時間去分析和對比，如何選擇一個適合本身團隊的 API 管理工具很是重要，由於這很大程度決定了團隊之間的協做方式。

爲何須要 API 管理

傳統的 API 管理是採用 word 文檔的方式，這種方式的缺陷在於它難以維護和管理，同時容易形成不一樣步，隨着時間的推移，API 文檔散落在各個地方，致使接口數據格式不一致，接口頻頻報錯，這會形成團隊之間的不信任，以至於 API 文檔逐漸被廢棄；這種狀況一發生，就會看到開發人員之間頻繁的經過詢問、溝通、聯調和查看代碼來肯定 API 接口的各類細節，團隊之間更容易互相推卸責任，開發成本逐漸增長。

有趣的是，這種問題不是給開發團隊 丟一個功能超強的 API 管理平臺就能夠搞定的。這須要使用合適的管理策略。

咱們真正須要的是什麼

不妨從結果導向來看，若是站在 API 接口的消費端角度，那咱們須要的 API 文檔必須具備如下幾個重要特徵：

1. 描述恰當
2. 劃分合理
3. 及時同步
4. 經過測試
5. 方便使用

這個時候咱們就會發現，這些東西，基本上都是人來作，平臺和工具只不過提供更加好看的界面，更加方便的工具來幫咱們更快的作到第 三、4 點。這個時候咱們才恍然大悟，API 管理重點在人，不在工具。

如何管理

誰產生，誰負責管理。 爲了讓這種理念變得更容易被接受，須要把它行成一種習慣，所以最好跟對方最擅長的技能結合在一塊兒，加上適當約束，而且賦予這我的必定的權利。

• 工具最好跟代碼結合（慢慢造成習慣）。
• 經過測試（約束）。
• 擁有部分接口的定義權（賦予必定的權利）。

平臺分析

在線產品

這種產品很是多，基本上能夠歸爲 免費 和 收費 兩種，部分產品提供更多額外的服務，例如監控、自動化測試等。

優點

1. 不須要維護服務器
2. 提供團隊協做功能
3. 提供在線接口測試
4. 接口變動通知（不必定有）
5. 多項目管理

劣勢

1. 平臺隨時可能 中止維護
2. 接口須要手工同步
3. 各大平臺的 接口格式 不太統一，遷移是問題
4. 接口契約沒法保證（是否經過測試？格式是否正確？）

框架集成

框架集成是指 把 API 文檔自動生成框架集成到 開發環境中，目前 基於 spring 的主要有 springfox-swagger2 和 spring rest doc。

Springfox-Swagger2

劣勢

1. 侵入式
2. 增長少許的學習成本

優點

1. 安全，可定義接口訪問鑑權
2. 代碼即文檔
3. UI 美觀
4. 提供測試
5. 社區提供 spring-boot 集成

Spring REST Doc

產品的定位是測試驅動 API 文檔，提供手寫文檔和自動生成相結合，基於 API 測試來自動生成文檔，只有測試經過才生成 API 文檔，所以能夠保證文檔的準確性。

劣勢

1. 增長少許的學習成本
2. 文檔須要 一點手工配置，好在配置相對簡單
3. 發佈接口前須要付出一些時間來執行 api 測試

優點

1. 安全，可選擇文檔共享範圍
2. 無侵入性
3. 接口契約（API 測試經過後，才能生成離線 html API 文檔）
4. 代碼即文檔
5. spring 生態，集成方便

自建

當框架集成 和 公網在線平臺 都不能知足須要求時，便可自建 API 管理平臺。目前這方面的開源工具也不少，經常使用的在思惟導圖中列出。

優點

1. 可控
2. 可定製

劣勢

1. 須要維護服務器
2. 接口須要手工同步
3. 接口契約沒法保證（是否經過測試？格式是否正確？）

總結

文章表達了我本身對 API 管理的見解，也簡單分析了市場上的一些 API 工具，粗粒度地總結了不一樣產品的選擇的優劣勢。API 管理的目標，是爲了便於團隊協做。在基於上面那些理解以後，我居然發現 Spring REST Doc 是最符合的。