但是，管理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開發體驗。
REST API自動化文件生成
一種rest api自動化文件生成能力 但是，管理rest api並非是一件容易的工作。由於缺乏有效的介面資料schema約束，加上設計rest api時resource endpoint的安排，以及傳送http請求的方式又都五花八門，rest api開發完成後，大多數情況下api開發者仍然需要手動...
beego自動化文件
beego是乙個快速開發go應用的http框架，go 語言技術大牛asta謝的開源專案。beego可以用來快速開發api web以及後端服務等各種應用，是乙個restful的框架，主要設計靈感 於tornado sinatra flask這三個框架，結合了go本身的一些特性 inte ce stru...
beego自動化文件
beego是乙個快速開發go應用的http框架，go 語言技術大牛asta謝的開源專案。beego可以用來快速開發api web以及後端服務等各種應用，是乙個restful的框架，主要設計靈感 於tornado sinatra flask這三個框架，結合了go本身的一些特性 inte ce stru...