java api文档_细说API – 文档和前后端协作
在上一篇文章——《細說API – 重新認識RESTful》中介紹了如何理解和設計RESTful風格的API，現在我們來聊聊如何有效的呈現API文檔，以及前后端協作的方式。
我經歷過一些沒有文檔的項目，前后端開發者坐到一起口口相傳，或者有些團隊用 word、pdf 來編寫 API 文檔。API 文檔的缺乏給前后端協作帶來困難，在缺乏專門工具的情況下，編寫和維護文檔是一件工作量巨大的事，人工處理也非常容易出錯。
本文將會介紹三種方案來解決前后端協作的問題：
基于注釋的 API 文檔
apidocjs 是生成文檔最輕量的一種方式，apidocjs 作為 npm 包發布，運行在 nodejs 平臺上。原理為解析方法前面的注釋，使用方法非常類似 javadoc 等程序接口文檔生成工具，配置和使用都非常簡單。因為只是解析代碼注釋部分，理論上和編程語言無關。
安裝：
npm install apidoc -g
在需要輸出文檔的源代碼中添加一個一個注釋示例：
最小化運行：
apidoc -i myapp/ -o apidoc
即可在 apidoc 中輸出靜態的 html 文檔目錄。如果指定配置文件 apidoc.json 可以定義更多的操作方式，也可以自定義一套 HTML 模板用于個性化顯示你的 API 文檔，另外在輸出的 HTML 文檔中附帶有API請求的測試工具，可以在我們生成的文檔中嘗試調用 API。
使用 apidocjs 只需要添加幾個例如 @api、@apiname、@apiParam 等幾個必要的注釋即可，值得一提是 @apiDefine 可以定義變量避免重復書寫，@apiGroup 用來對 API 分組，@apiVersion 可以再生成不同版本的文檔。
基于反射的 API 文檔
apidoc 的缺點是需要維護一些注釋，當修改源代碼時需要注意注釋是否同時被更新。不過如果你使用的是 Java、.Net 等強類型語言，就可以利用強類型語言的優勢。
在這個領域最好用的文檔工具當屬 swagger，swagger 實際上是一整套關于 API 文檔、代碼生成、測試、文檔共享的工具包，包括 :
通常我們提到 swagger 時，往往指的是 swagger ui。而在 Java 環境下，可以通過 Springfox 來完成對代碼的解析，再利用 swagger 生成文檔，下面我們給一個簡單的例子看怎么給一個 Spring boot 項目生成文檔。
首選加入依賴（gradle 同理）：
全局配置：
我們的 controller，需要定義一些必要的注解來描述這個 API 的標題和解釋，我們返回的 user 對象是一個簡單 value object，swagger-annotations 包下面提供了很多注解可以滿足更多的定制需求。
然后訪問你的 context 下的 /{context}/swagger-ui.html 頁面，你會看到一個漂亮的 API 在線文檔。swagger 的文檔上能看到具體的字段定義和 Model，如果修改了 Model，再次編譯后則可以自動反應到文檔上，這也是反應了強類型編程語言的優勢之一。
基于契約的前后端協作
在過去的開發中，往往是后端開發者占主導，像上面的兩種方案中，直接注釋、反射通過生成 API 文檔。
但前后端分離后讓合作方式發生了變化。傳統的方式往往是服務器開發者完成了 API 開發之后，前端開發者再開始工作，在項目管理中這樣產生時間線的依賴。理想的情況下，在需求明確后，架構師設計，前后端應該能各自獨立工作，并在最后進行集成測試即可。
后端開發者可以根據文檔實現接口，最后按照文檔聯合調試即可，甚至通過契約生成 API 調用和數據承載的 VO (Value Object)，減少工作量。如果 API 的提供者想做的更為完善一些，可以使用契約文件來驗證實際 API 輸出輸出是否合理。
契約測試
當我們使用契約文件來提高前后端協作開發的體驗，其中很重要的一部分就是契約測試，關于契約測試，我們一般指的是 Martin Fowler 提出的概念 —— “消費者驅動的契約”
簡單來說，就是前后端開發者協定好后，由消費者驅動，通過編寫 API 調用層相關的代碼，可以直接生成契約文件。由于一個 API 可以被多處消費，所以消費者驅動可以更好的管理契約的變化（如果 API 驗證契約時不能通過，說明契約被破壞了，可以在 CI 上馬上反應出來）。
(Pact 契約測試模型)
寫契約測試的博客非常多，就不展開贅述了。我把契約測試放到了前后端協作這個部分，是因為契約測試的前提是建立在前后端良好的協作下實現的。“契約測試”關注的是契約，而不是測試。
實際工作中，退一步說，制定好契約就可以完成基本的開發工作，對契約測試、驗證可以讓前后端協作變得更為可靠。如果你現在還沒準備好使用契約測試的話，也不必焦慮，手動定義契約可以讓前后端協作先運行起來。
而如果你恰好使用了 Spring boot 全家桶的話，不妨看看 Spring cloud contract。
使用 Swagger Yaml 契約
前面在講 swagger 的時候，提到了Swagger Editor，使用這個工具可以通過編寫 API 定義文件（Yaml格式），它提供線上版本，也可以本地使用。
后端通過生成 API 定義文件，就可以進一步完成生成 HTML 靜態文檔、模擬 API 數據等操作。
前端開發者可以通過 swagger 的 node 版本 swagger-node 自帶的 mock 模式啟動一個 Mock server，然后根據約定模擬自己想要的數據。 關于在前端使用的 mock server，實在太多，而且各有優劣，在附錄中有一個清單以供參考，不再贅述。
使用 RAML 契約
使用 Swagger Yaml 契約或者 Pact 契約都能在一定程度上完成契約測試、生成文檔、mock 等工作，但是我們在實際工作中發現這些工具和平臺的契約規則并不相同。
Swagger 在生成文檔上非常優秀，然而在契約測試上不及 Pact，反之亦然。
隨著引入微服務和開放的互聯網項目越來越多，前后端協作的問題越來越明顯，而解決上述問題的工具和技術并不通用。好在業界早已認識到這個問題，于是一些組織提出了 RestFul API 統一建模語言 （RESTful API Modeling Language），也就是 RAML。
圍繞著 RAML 這一標準，構建出 API 協作的工具鏈，設計、構建、測試、文檔、共享。
其他前后端協作實踐
中心文檔服務器
在一個大型的團隊中，可能會有幾十個以上的項目同時提供了 API，這種情況下如果每個應用都各自提供API文檔就會變得很難管理，如果將 API 文檔綁定到應用服務上會帶來一些無意義的損耗。可以使用一個集中地服務來存放這些文檔，類似于 github 的私有倉庫，swagger 同樣也提供了類似的服務 – swaggerhub.com。
即使不使用 swagger ，我們可以構建出 HTML 文檔然后每一次輸出部署到一臺靜態服務器，也是非常容易的事情。
管理契約文件
既然是契約文件，就不應該是API提供者或者消費者單獨擁有的，即使只有一個調用方，至少是前端、后端共同擁有的。
那么契約文件應該怎么放呢？
我們之前一直放到API的代碼倉庫中，然后給所有的人添加了權限。后來發現這樣做非常不方便，于是單獨增加了一個管理契約文件的 git倉庫，并使用 git 的submodule 來引用到各個涉及到了的代碼倉庫中。
將契約文件單獨放置還有一個額外的好處，在構建契約測試時，可以方便的發送到一臺中間服務器。一旦 API 契約發生變化，可以觸發 API提供的契約驗證測試。
附錄：API 文檔工具清單
- 使用或調研過的，API 文檔/契約生成工具
- 使用或調研過得 mock 工具清單
- HTTP 請求攔截器
- 契約/API 測試工具
更多精彩洞見，請關注微信公眾號：ThoughtWorks洞見
總結
以上是生活随笔為你收集整理的java api文档_细说API – 文档和前后端协作的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： if test 多条件_if函数进阶篇
- 下一篇： 多个线程访问统一对象的不同方法_不会多线