API的文檔自動生成——基于CDIF的SOA基本能力

當前，作為大部分移動app和云服務后臺之間的標準連接方式，REST API已經得到了絕大部分開發者的認可和廣泛的應用。近年來，在新興API經濟模式逐漸興起，許多廠商紛紛將自己的后臺業務能力作為REST API開放出來，給更廣泛的第三方開發者使用。

但是，管理REST API并非是一件容易的工作。由于缺乏有效的接口數據schema約束，加上設計REST API時resource endpoint的安排，以及發送http請求的方式又都五花八門，REST API開發完成后，大多數情況下API開發者仍然需要手動書寫API文檔，讓用戶能按照文檔的說明接入。并且在API發生變化時需要重寫文檔，這個過程費時費力而且容易出錯。比如，一個REST API文檔最少必須列明以下的基本信息：

* API的名稱

* API所在的URL資源路徑

* http請求方法（GET, POST, PUT等）

* API提交數據的方式（查詢參數、表單提交、JSON提交等）

* 調用API返回數據的格式

在上面提供的REST API信息中，從API返回的JSON數據在大部分情況下甚至只能用“舉例”的方法說明數據的結構，而無法精確表達出這段JSON數據中每個字段的精確含義和類型定義。這都是因為REST API缺少對JSON數據的schema定義而導致，而這種“舉例”的方式毫無疑問是一種很無奈很傻的做法。我們在開發時對接其他廠商的接口時，經常會發生對方的文檔不清晰，需要人工確認交流，甚至聯調我們對某個數據參數或者返回結果的理解是否正確，這是一個非常耗時耗力的工作。

而當業務發生變化，以上任何一項關于REST API的信息發生變化時，比如返回結果里添加了一個新的字段，開發者又必須重新手工書寫文檔，然后把文檔重新發送給API使用者更改，以上的過程如果反復迭代則會非常痛苦。當前雖然有一些API設計和文檔工具，比如Swagger UI等用Yaml語言幫助開發者更容易地書寫文檔，但并沒有消除REST API天生帶來的上述復雜性。

這種API管理解決方案則完美地解決了上述的REST API文檔問題。CDIF是世界上第一個基于JSON的SOA解決方案。被CDIF管理的REST API都可以自動生成他們的API文檔，大大節省了開發人員管理API文檔的時間精力。CDIF的框架設計可以用下圖表示：

在上圖中，CDIF將REST API統一封裝成各種驅動包，每個驅動包都是一個標準的node.js npm package。每個驅動包中可包含任意多條REST API的訪問代碼。在驅動包的實現中，按照CDIF提供的規范，每個REST API必須為客戶端提供一個統一通用的API模型。這個API模型是一份JSON文檔，里面包含了所有關于如何訪問這個API的信息。而相比起以上的REST API文檔，這份API模型中僅僅包含以下信息：

* API的名稱

* API輸入參數和返回結果的JSON schema定義

而關于REST API的其他信息都被看成是API驅動包的內部實現，不需要暴露給外部API使用者。

基于CDIF定義規范的API模型擁有與基于XML的WSDL同等能力的API描述。在此基礎上，與CDIF配套的API管理工具可以自動解析這份JSON文檔，并自動從中生成被其管理REST API的文檔。下圖是利用CDIF制作的API市場上自動生成的清晰易讀的短信API文檔截圖：

在以上的API文檔中，所有請求和返回數據中每個字段的類型，說明，約束條件，API的錯誤信息等等，全部都從用戶在API包中提供的JSON schema文件中自動生成，并且真正做到了對API以及數據100%準確的描述。開發者只需要按照CDIF提供的規范定義寫好API模型，上傳一個僅包括幾十行API訪問代碼的npm包到基于CDIF的的API管理平臺，便可擁有該能力。而在API參數或返回結果需要更新時，用戶只需要更新npm包中的JSON schema文件的內容，重新上傳便可自動獲得新的API文檔。

而訪問這個被CDIF管理的REST API時，使用者只需要訪問CDIF為被其管理的REST API提供的一個固定URL地址便可，并且也只需要客戶端支持http POST方法即可提交API請求數據。所有提交的數據，按照JSON schema的約束，全部都放在http請求和返回的JSON body中。這樣的設計是經典的WSDL + SOAP的實現方式，非常簡單易用而且兼容性好。同時，借助于JSON schema的強大表現能力，CDIF可以支持任意復雜度的API接口數據。目前絕大多數流行的開發語言都支持用post JSON數據的方式提交API請求，所以CDIF提供的API訪問接口已經可以得到最廣泛的客戶端開發環境支持。在將來，我們會添加各種語言的客戶端API訪問代碼自動生成能力，API使用者只需拷貝粘貼代碼即可接入，更進一步簡化方便API的開發和使用流程。

另外，在API包的內部實現需要變化時，用戶只需要修改API包的代碼，重新上傳并可一鍵部署新版本使用。CDIF支持對API包代碼的熱切換，甚至不會影響線上正在發生的對老版本API的調用過程。這樣大大方便和簡化了開發者的API開發體驗。

不僅如此，上傳API包后開發者還可以自動擁有API測試頁面，可供API開發者和API使用者更方便地調試API的可用性。這個功能，敬請大家參考下一篇文章：API測試自動化——基于CDIF的SOA基本功能。