REST API自動化文檔產生

這是一個建立於 的文章，其中的資訊可能已經有所發展或是發生改變。

一種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的可用性。下期我們再介紹我們提供的這個這個功能，敬請大家關注。

CDIF架構和基於CDIF的API管理解決方案目前由上海靈長軟體科技有限公司負責開發，並開放給所有API開發人員使用，歡迎大家來我們的網站 apemesh.com註冊並申請試用我們的API管理解決方案。