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

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

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

* API的名稱

* API所在的URL資源路徑

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

* API提交數(shù)據(jù)的方式（查詢參數(shù)、表單提交、JSON提交等）

* 調(diào)用API返回數(shù)據(jù)的格式

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

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

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

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

* API的名稱

* API輸入?yún)?shù)和返回結果的JSON schema定義

而關于REST API的其他信息都被看成是API驅(qū)動包的內(nèi)部實現(xiàn)，不需要暴露給外部API使用者。

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

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

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

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

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