如何生成rest api文檔？

01-05

小幺雞，簡單好用的在線介面文檔管理系統

支持在線測試，經測試（可降低介面錯誤率）。

支持json，js，websocket，二進位測試。

支持restful介面。

而且還是開源的。

Swagger：Rest API的描述語言 - 用心閣的文章 - 知乎專欄

API Blueprint

教程：api-blueprint/Tutorial.md at master · apiaryio/api-blueprint · GitHub

文檔：api-blueprint/API Blueprint Specification.md at master · apiaryio/api-blueprint · GitHub

工具：Apiary

重點在於「生成」，swagger和api blueprint選型時都考慮過，最終還是選擇了apidocjs，使用它擴展的javadoc annotation很方便，文檔與代碼一體化

http://apidocjs.com

如果從設計階段開始，不嫌麻煩的話，可以採用RAML，mule提供了在線編輯器，eclipse也有插件可以由JAX-RS的java代碼生成。

Swagger 2.0

可視化編輯器(含例子) ： Swagger Editor

Github: Swagger · GitHub

華為和中興員工 酷愛的文檔神器

可以滿足您！

如果是從代碼生成對應的API 文檔的話，目前只有swagger和raml支持的比較好。

但是api blueprint 支持swagger converter 進行文件轉換。

現在API方面這三個算是並駕齊驅吧，我比較喜歡api blueprint ，因為文檔看起來比較清晰，apiary這個網站也提供了文檔，mock，測試等功能。

一種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開發者使用，歡迎大家來我們的網站 http://apemesh.com註冊並申請試用我們的API管理解決方案。