目錄
規范的接口文檔管理方式有助於提高組件協同（如：前后端分離）的開發效率，對於項目的接口說明有全局的管理視角，甚至可以方便地實現對外發布。
完善的文檔管理應該包含文檔格式和文檔管理方式這兩部分，如下一一解釋。
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使用————接口參數注解的使用缺陷
https://blog.csdn.net/xiaojin21cen/article/details/78654652 swagger2 注解說明
https://blog.csdn.net/cy921107/article/details/82761575 Swagger2 關於JSONObject參數在API文檔中展示詳細參數以及參數說明
http://www.voidcn.com/article/p-bxgydblc-bnz.html 如何利用Swagger消除前后端分離的障礙？
https://www.cnblogs.com/softidea/p/6226463.html Swagger專題
https://www.cnblogs.com/ceshi2016/p/10511959.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 的比較
https://www.cnblogs.com/minsons/p/7133095.html Api管理工具（spring-rest-docs）