[TOC] # 簡介 現在的網站架構基本都由原來的后端渲染，變成了：前端渲染、先后端分離的形態，而且前端技術和后端技術在各自的道路上越走越遠。 前端和后端的唯一聯系，變成了API接口；API文檔變成了前后端開發人員聯系的紐帶，變得越來越重要，swagger 就是一款讓你更好的書寫API文檔的框架。 # 其他API文檔工具 類似的API文檔工具網上還有很多，但是能拿上臺面的，不多。RAP是由阿里開發的，整個阿里都在用，還不錯。github地址為：https://github.com/thx/RAP 當然咯，rap 不可能只有線上版本，肯定可以[部署到私服](https://github.com/thx/RAP/wiki/deploy_manual_cn)上。 # [Swagger](https://github.com/swagger-api) 方便的管理項目中API接口，目前最流行的莫過于Swagger了，功能強大，UI界面漂亮，并且支持在線測試等等。 Swagger 是為了描述一套標準的而且是和語言無關的 REST API 的規范。對于外部調用者來說，只需通過Swagger文檔即可清楚Server端提供的服務，而不需去閱讀源碼或接口文檔說明。 中文網站：http://www.sosoapi.com ## 三大功能 1、**[Swagger Editor](http://editor.swagger.io/)**: Swagger提供的一個編輯器，用來通過Swagger提供的特定的YAML語法來編寫API文檔。 2、**Swagger Codegen**: 代碼生成器 3、**[Swagger UI](http://petstore.swagger.io)**: YAML語法定義我們的RESTful API，然后它會自動生成一篇排版優美的API文檔，并且提供實時預覽。 # 產生的背景 **前后端分離** 1、前后端僅僅通過異步接口(AJAX/JSON)來編程 2、前后端都各自有自己的開發流程，構建工具，測試集合 3、關注點分離，前后端變得相對獨立并松耦合 ## 面臨問題 1、沒有統一的文檔編寫規范，導致文檔越來越亂，無法維護和閱讀。 2、開發中的接口增刪改等變動，需要較大的溝通成本。 3、對于一個新需求，前端開發的接口調用和自測依賴后臺開發完畢。 4、將接口的風險后置，耽誤項目時間。 ## 解決方法 1、接口文檔服務器 -- 解決接口文檔編輯和維護的問題。 2、mock 數據 -- 解決前端開發依賴真實后臺接口的問題。 ## 接口文檔服務器 后臺通過引入 Swagger 的相關依賴包和配置。 后端 Java 代碼通過配置 Swagger 相關注解，可以更好地解釋 API 。 最后，為前端提供 Swagger-UI 地址，啟動服務后，訪問：http://localhost:8080/swagger-ui.html 就完成了集成。 # [SosoApi](https://github.com/sosoapi) 是一個專注于API接口文檔管理及線上線下測試的API服務平臺。 ## 特點 ? 提供豐富的在線文檔，包括線上編輯和線下部署及常見問題，減少上手學習成本。 ? 通過編輯表單的方式創建基于swagger ui的數據文檔，從而可在線預覽和測試。 ? 解決了swagger editor學習成本高及代碼集成不好維護的問題。 ? 為方便小團隊及公司內部使用，可導出swagger數據文檔線下部署。 ? 不會對已有項目產生任何代碼入侵。 ## 使用 登錄[官網](http://www.sosoapi.com/)使用，上面有詳細的指導手冊，大家一看就明白了。這里主要補充一點：sosoapi 去年還沒有添加“導入”的功能，今年增加了，但只有在線的版本有導入功能，開源版本沒有，所以筆者推薦使用在線版本以節省人力。有了導入功能，那么只要導入接口的 json 文件就可以自動生成接口文檔了（剛好 swagger 可以生成 json 文件），我們只要輸入必要的參數就可以進行測試了。 ## 配合 同時使用 Swagger 和 [SosoApi](http://www.sosoapi.com/)，使用Swagger生成 json 文件，然后將 json 文件導入 sosoapi，就可以得到接口文檔及可導出多種格式的接口文檔。 # 契約測試 談到了前后端分離，那么在所難免，會遇到一些集成的問題：一撥人在全心全意的進行前端開發，另一撥人在心無旁騖的做后端開發，那么誰應該為集成買單呢？在現在這個持續集成、持續交付的年代里，我們應該如何去保證雙方不會分道揚鑣、越走越遠呢？ 所以，在一開始就定一個契約就成了迫在眉睫的事情，雙方就API相關的內容，包括路徑、參數、類型等達成一致，當然，這份契約并不是一旦創建就不能修改的，而且，如果一開始沒有設計好，很有可能會頻繁的修改。這個時候，要讓雙方都能夠實時的跟蹤最新的API就成了一個難題。還好，在總結了前人的經驗和教訓之后，我們早已有了應對之策，那就是契約測試。 首先，我們先假設我們已經有了一份契約，可能是基于JSON格式的，有可能是基于XML格式的，這都不重要。然后，前端會根據這份契約建立一個Mock server，所有的測試都發往這個Mock server。有兩方面的原因：一是這個時候可能后臺的API還沒有開發完成；二是有可能因為網絡等其他方面的原因導致直接調用真實的后臺API會很不穩定或者很耗時。到這里，可能有人就要說了，如果后臺的API實現和之前約定的并不一樣，怎么能保證到了集成的時候雙方還能很順利的集成呢？其實這個問題并不難，只需要讓前端的測試定期連接真實的API執行一遍就能盡早的發現差異性。比方說，在我們平常的build pipeline上添加一個job，讓這些測試每天在午夜里連著真實的API執行。如果，第二天發現這些測試有的失敗了，那么就需要和開發后臺API的人員進行一次溝通了，很有可能由于真實的業務邏輯發生了變化，API在實現的時候，已經和之前的契約不一致了，如果是這樣，那么相應的測試和契約定義就需要更新以滿足最新的業務需求。 總之，進行契約測試的目的就是盡早的發現差異性，并作出調整，將最后集成的風險降到最低。 # 參考 [http://apijson.org/](http://apijson.org/) # [RESTful API 設計指南](http://www.ruanyifeng.com/blog/2014/05/restful_api.html)