一種rest api自動化文件生成能力
但是，管理rest api並非是一件容易的工作。由於缺乏有效的介面資料schema約束，加上設計rest api時resource endpoint的安排，以及傳送http請求的方式又都五花八門，rest api開發完成後，大多數情況下api開發者仍然需要手動書寫api文件，讓使用者能按照文件的說明接入。並且在api發生變化時需要重寫文件，這個過程費時費力而且容易出錯。比如，乙個rest 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模型中僅僅包含以下資訊：
而關於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開發體驗。
cdif框架和基於cdif的api管理解決方案目前由上海靈長軟體科技****負責開發，並開放給所有api開發者使用。
為REST API新增自動化文件生成能力
但是，管理rest api並非是一件容易的工作。由於缺乏有效的介面資料schema約束，加上設計rest api時resource endpoint的安排，以及傳送http請求的方式又都五花八門，rest api開發完成後，大多數情況下api開發者仍然需要手動書寫api文件，讓使用者能按照文件的說明...
Hapi MySql專案實戰自動化文件生成（四）
使用hapi外掛程式hapi swagger,簡單配置下外掛程式，先修改下plugin config.js檔案 plugin config.js const swaggeroptions module.exports 修改routes login.js檔案，如下 login.js const joi...
beego自動化文件
beego是乙個快速開發go應用的http框架，go 語言技術大牛asta謝的開源專案。beego可以用來快速開發api web以及後端服務等各種應用，是乙個restful的框架，主要設計靈感 於tornado sinatra flask這三個框架，結合了go本身的一些特性 inte ce stru...