細說RESTful API之文檔管理

目錄

• API文檔格式
• 文檔管理方式
  • 基於註解實現，代碼和文檔在一塊兒
    • Swagger
    • Api2Doc
  • 基於API測試工具生成
    • Postman
    • rest-client
  • 獨立編寫文檔
    • RAP
    • DOClever
    • APIDOC
    • CrapApi
• 寫在最後

規範的接口文檔管理方式有助於提升組件協同（如：先後端分離）的開發效率，對於項目的接口說明有全局的管理視角，甚至能夠方便地實現對外發布。
完善的文檔管理應該包含文檔格式和文檔管理方式這兩部分，以下一一解釋。

API文檔格式

規範的API文檔格式有助於理解，能夠大大提升開發效率，下降沒必要要的溝通成本。
可是，並不是須要採用統一的格式進行約束（畢竟不一樣的項目要求不通，不一樣的架構師風格也各異），有的人喜歡用Word編寫，有的人卻恰恰愛好Markdown語法。總之，不論採用何種格式，必定要對API接口進行完整的，清晰的描述（如：接口功能，方法定義，參數含義，返回格式等等）。
若是團隊中尚未統一的API文檔格式規範，能夠參考螞蟻金服API文檔格式示範進行設計。

文檔管理方式

RESTFul API文檔管理方式（生成，維護）大體能夠分爲3類：

基於註解實現，代碼和文檔在一塊兒

基於註解生成文檔的好處是代碼和文檔在一塊兒，不用單獨維護一份文檔；缺點也很明顯，須要在業務代碼中嵌入文檔註解，會使得代碼顯得很雜亂。
基於註解方式實現文檔管理的典型工具備：Swagger，Api2Doc。

Swagger

Swagger是一個很流行的RESTFul文檔生成工具，可是若是須要生成一個相對規範和完善的文檔，要編寫太多註解，很繁瑣，詳見： https://swagger.io/ 。
關於使用Swagger實現對接口文檔進行管理能夠參考以下資源：
https://github.com/swagger-api Swagger GitHub項目官網
https://www.jianshu.com/p/33c28a65deb8 Swagger-強大的API文檔工具
https://blog.csdn.net/zhangxin09/article/details/82699353 Swagger 2（Open API v3.0） Java 文檔生成指南（上）
https://www.ibm.com/developerworks/cn/java/j-using-swagger-in-a-spring-boot-project/index.html 在Spring Boot項目中使用Swagger文檔
https://blog.csdn.net/u014745069/article/details/80246803 Swagger使用————接口參數註解的使用缺陷
http://www.javashuo.com/article/p-xoxiqszl-dn.html swagger2 註解說明
http://www.javashuo.com/article/p-mmfpvgjn-my.html Swagger2 關於JSONObject參數在API文檔中展現詳細參數以及參數說明
http://www.voidcn.com/article/p-bxgydblc-bnz.html 如何利用Swagger消除先後端分離的障礙？
http://www.javashuo.com/article/p-zvpicnqi-gr.html Swagger專題
http://www.javashuo.com/article/p-cbotzicp-gv.html Swagger Annotation 詳解（建議收藏）

Api2Doc

Api2Doc原理相似Swagger，可是基於Spring Boot框架。
目前該工具還不完善，集成1.0.2版本時報錯，詳見：
https://github.com/terran4j/commons/tree/master/commons-api2doc api2doc官網

基於API測試工具生成

代碼和文檔分離，可是不須要單獨編寫文檔，在接口測試時就能夠生成文檔。

Postman

Postman就支持根據請求發佈爲可在線查看的API文檔，若是須要考慮權限和保密性可能不適合。
http://book.crifan.com/books/api_tool_postman/website/postman_api_doc/preview_publish_api_doc.html 預覽和發佈API文檔

rest-client

rest-client是我的開源的相似postman的REST API測試工具，能夠根據API直接生成離線API文檔，基於Java Swing編寫的GUI界面。
https://github.com/Wisdom-Projects/rest-client

獨立編寫文檔

獨立維護API文檔是最簡單的方式，可是缺點也很明顯，那就是可能代碼與文檔的同步不及時，甚至可能會出現文檔是過時的。
可使用任何喜歡的格式編寫獨立的API文檔，根據需求能夠設計成在線（目前不乏有許多在線API管理系統）或者離線（例如：可使用Execel表格，MarkDown語法編寫，甚至是Word）的格式。

以下是幾款流行的基於Web的API管理工具，分別簡單介紹：

RAP

官網：https://github.com/thx/RAP
RAP是阿里開源的Web接口管理工具，開源免費，支持接口自動化，MOCK數據自動生成，自動化測試，企業級管理。
雖然RAP的功能比較全，可是卻不支持JSON格式的請求參數，差評。

DOClever

DOCleven是一個商業的API管理系統，官網：http://doclever.cn/controller/index/index.html。
有開源版本，詳見：https://github.com/sx1989827/DOClever。
雖然DOClever號稱功能很是強大並且全面，可是開源版本裁剪得實在是太精簡了，不太適合拿過來直接用，基於它搞二次開發能夠。
開源版安裝時建議不要使用npm安裝，啓動時各類報錯，使用源碼安裝沒有這個問題。

# 在安裝DOClever以前先安裝並啓動MongoDB
# 使用源碼方式安裝DOClevere
$ git clone https://github.com/sx1989827/DOClever.git
$ cd DOClevere
$ npm start

若是啓動報錯，建議使用node版本爲8.11.1。

APIDOC

對於獨立編寫API文檔的另一個工具是APIDOC，官網：http://apidocjs.com。
相對於普通的接口文檔管理工具，APIDOC走了一條比較清奇的路子。它經過接口（注意：這個接口不是業務接口，而是專門用於生成文檔的接口）方式定義API，本質上也是在業務代碼以外維護接口文檔。
https://blog.csdn.net/soslinken/article/details/50468896 使用apidoc生成Restful web Api文檔
https://blog.csdn.net/qq_27384769/article/details/78622831 apidoc使用教程-編寫漂亮的api文檔

CrapApi

CrapApi是目前開源產品中最滿意的了，基本的API文檔管理是比較全面的了，可是對於MOCK測試的支持還比較弱。
可是有利有弊，對於一款開源系統而言，核心功能已經不錯了，推薦使用，詳見：https://gitee.com/CrapApi/CrapApi 。
CrapApi的安裝很是簡單，它自己是一個傳統Java Web項目，最終打包格式爲war文件，因此只須要將war包放到Tomcat的webapps目錄下便可訪問。
值得注意是：因爲CrapApi源碼中的SQL腳本是使用工具導出的，裏面的註釋（主要是格式爲/***/的註釋）在某些SQL工具下可能會報錯，直接刪除便可。

寫在最後

對於API的文檔管理方式多種多樣，可是沒有一個方案就是必定是完美的，各自都有本身的優勢和不足，主要體如今：
1.在代碼中維護文檔，在Java中能夠經過註解來完成，最有利於維護代碼和文檔的一致性，可是爲了生成一份相對完善的文檔須要添加一堆註解，這會污染真正業務代碼的簡潔性，甚至會有性能損耗的缺陷；
2.獨立編寫文檔的方式雖然不會污染業務代碼，可是因爲代碼與文檔徹底分離，會隱形地增長了維護代碼與文檔一致性的成本；
3.相對而言，基於API測試工具生成文檔的方式比較折中，可是生成文檔的功能與工具自己綁定得很是緊密，很難進行私有化部署和權限管理。

實際上，不管採用哪一種方式，對於文檔的維護都須要必定的規章制度來硬性保證及時更新。「程序員都不喜歡寫文檔，卻又都但願別人寫文檔」，這是開發者的通病，即便採用在代碼中維護文檔（如：Swagger）的方式，若是開發者習慣很差或者沒有約定強制開發者及時維護更新文檔，依然不能解決文檔與代碼同步的問題，畢竟這是須要人去驅動的（參數的變動，方法的增長一樣須要注入對應的文檔註解）。
因此，對於API文檔的維護沒有萬能的解決方案，不論採用何種文檔維護方式都必須有對應的制度強制執行，不然再好的工具使用很差依然沒有意義。至於選擇什麼樣的文檔管理方式，依賴於架構師的喜愛，或者根據項目自己的實際需求（如：是否須要對外發布等因素）來選定合適的方案便可，畢竟不管採用何種手段都只是達成目標的一個工具，關鍵在於如何高效地使用。

【參考】
https://www.jianshu.com/p/be32a38f408d API接口管理之道
https://blog.csdn.net/vimx86/article/details/78381838 接口文檔管理方案
https://hacpai.com/article/1519833837647 API 管理工具 Swagger 和 RAP 的比較
http://www.javashuo.com/article/p-ckfjeupd-gt.html Api管理工具（spring-rest-docs）