爲REST API添加自動化文檔生成能力

當前，做爲大部分移動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的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的文檔。下圖是靈長科技的API市場上自動生成的清晰易讀的短信API文檔截圖：

以上截圖詳細內容可參考靈長科技API市場

在以上的API文檔中，全部請求和返回數據中每一個字段的類型，說明，約束條件，API的錯誤信息等等，所有都從用戶在API包中提供的JSON schema文件中自動生成，而且真正作到了對API以及數據100%準確的描述。開發者只須要按照CDIF提供的規範定義寫好API模型，上傳一個僅包括幾十行API訪問代碼的npm包到靈長科技的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框架和基於CDIF的API管理解決方案目前由上海靈長軟件科技有限公司負責開發，並開放給全部API開發者使用，歡迎你們來咱們的網站 https://apemesh.com 註冊並申請試用咱們的API管理解決方案。