上周看到有人在我的Github開源項目中提了個issue，說是否考慮接入swagger。那今天我就用swagger與其他接口文檔工具做對比，同時說說Api接口文檔工具的那點事。如今，在前后端分離開發的這個年代，Api接口文檔管理工具越來越顯得重要。完整的Api接口文檔能大大提升前后端開發協作的效率。
目前市場有哪些比較優秀的接口文檔管理工具呢？Swagger Api接口文檔工具到底如何，我大致匯總一下吧！
一、Swagger
說到Swagger，他確實是為開發者發明的一款神器，他可以實現自動生成 API 接口文檔，在線調試，非常的方便。Swagger 官方文檔: https://swagger.io/。項目接入：pom依賴：
<!-- swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.4.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.4.0</version> </dependency> 配置信息：
@Configuration @EnableWebMvc @EnableSwagger2 public class SwaggerConfig extends WebMvcConfigurerAdapter { @Bean public Docket buildDocket() { Docket docket = new Docket(DocumentationType.SWAGGER_2) .apiInfo(buildApiInf()); docket = docket.select() .apis(RequestHandlerSelectors.any())//controller路徑 .paths(PathSelectors.any()).build(); return docket; } @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } private ApiInfo buildApiInf() { return new ApiInfoBuilder() .title("RestAPI Docs") .termsOfServiceUrl("http://www.github.com/kongchen/swagger-maven-plugin") .build(); } } Controller里的配置（例如）：
@Api(value="客戶API",tags={"客戶API"}) @RestController @RequestMapping("/api/customer/") public class CustomerController { /** * 更新采購商資料 * * @return * @throws Exception */ @ApiOperation(value="更新商戶信息", notes="根據Customer對象更新,SON格式：{\"id\":1,\"customerType\":\"..\",...}") @ApiImplicitParam(name = "Json", value = "", dataType = "Json",required = true) @ResponseBody @RequestMapping(value="update", method=RequestMethod.POST, produces = {"application/json;charset=UTF-8"}) public JSONObject updateCustomer(HttpServletRequest request) throws Exception{ //TODO 代碼邏輯 } } 啟動項目，打開swagger,界面：http://192.168.1.101:9001/swagger-ui.html，
再看看剛配置的接口：
Swagger的接入特別簡單，還可以在線調試。那么Swagger一定就很牛逼嗎，我們再看看他的優缺點。
Swagger的優點如下：
1、節省了大量手寫接口文檔的時間，這是最大的優勢；
2、生成的接口文檔可以直接在線測試，節省了使用Postman設置接口參數的過程，而且請求的參數，返回的參數一目了然；
3、接口按照模塊已經分類展示，結構清晰；
Swagger 的缺點****大致如下：
1、需要在代碼中寫大量的注解，生成的接口文檔越清晰，寫的注解越多；
2、對於復雜功能，一個功能需要多個模塊配合的情況下，聯調測試將會是一件非常麻煩的事。Swagger還不支持自定義接口文檔，不能指明某一個功能需要使用哪些接口；
3、對於返回結果不能添加說明或者實現這個功能非常麻煩。雖然 Swagger 有 @ApiResponse注解用來說明返回結果，但是這個使用並不方便，而且如果返回的並不是對象的時候(如 Map)，就無法實現給每一個返回字段的說明；
4、無法測試錯誤的請求方式、參數等。如接口指定使用 POST 請求，則無法使用 swagger 測試 GET 請求的結果，也無法自定義 Header；
5，分布式開發環境中，一個項目往往有多個接口服務（比如電商項目有app，pc，后台三個接口服務）。每一個接口服務都對應一個獨立的swagger文檔，不能實現統一整合。
二，apizza
Apizza也是我們項目中使用過的，是從Swagger 轉到Apizza。而卻他是極客專屬的api協作管理工具，免費的團隊協作，在線模擬調試，快速生成api文檔，導出離線版文檔。
項目Api接入：
只需在Apizza官網（https://apizza.net）申請賬號，創建項目，並手寫添加接口文檔。
主要功能
-
api跨域調試量身定制的chrome插件，本地，在線接口，都可以調。
-
雲端存儲，企業安全版支持本地數據中心。
-
一鍵分享，與團隊共享你的API文檔。
-
支持Postman，Swagger格式 導入Postman/Swagger Json 生成文檔。
-
導出離線文檔，部署本地服務器。
-
api Mock 根據文檔自動生成返回結果，提供獨立URL方便前端測試。
-
支持多種文檔 http接口文檔，markdown說明文檔。
Apizza接口文檔工具有一個很大不足的地方，那是Apizza個人免費版有人數****限制，所有超過8人的團隊如果想免費用，你是不用考慮Apizza的。如果你看到有文章或公眾號上說Apizza是免費的，那簡直是胡扯，他肯定沒用過。當然如果你不缺錢，可以付費開通企業版。我們團隊也是用了半年多Apizza，后來由於人員增加，Apizza里又無法再新添加新成員，迫使我們不得不放棄Apizza。
三，Yapi
Yapi是去哪兒網開源的一款接口管理工具。Yapi旨意將接口作為一個公共的可視化的方式打通前端、后台、測試環節，整合在一塊，共同使用維護，提高接口的維護成本。Yapi是一款免費開源的Api接口文檔工具，需要下載部署在自己的服務器上。Yapi也是我們現在正在使用的接口文檔工具。
主要特點如下：
- 權限管理 YApi 成熟的團隊管理扁平化項目權限配置滿足各類企業的需求；
- 可視化接口管理 基於 websocket 的多人協作接口編輯功能和類 postman 測試工具，讓多人協作成倍提升開發效率；
- Mock Server 易用的 Mock Server，再也不用擔心 mock 數據的生成了；
- 自動化測試 完善的接口自動化測試,保證數據的正確性；
- 數據導入 支持導入 swagger, postman, har 數據格式，方便遷移舊項目；
- 插件機制 強大的插件機制，滿足各類業務需求；
這里關於Yapi的安裝就不詳細介紹了。Yapi安裝需事先安裝nodejs、mongodb、git應用。今天主要講了我們使用過的Api接口文檔工具，整體來說，個人感覺這三款都不錯。在團隊很小的時候，實際那個都能滿足需求。但在團隊人數慢慢增加時，就需要考慮一些工具的局限性，這也是我們從Swagger到Apizza再到Yapi的原因。當然，除了上面這三個，市面上還有很多其他的Api文檔工具。如：eoLinker、ShowDoc、easydoc、MinDoc等。說了這么多，那具體用哪一個呢？這需要根據自己的團隊等情況選擇一款最適合自己的。
掃碼關注公眾號，發送關鍵詞獲取相關資料：
-
發送“Springboot”領取電商項目實戰源碼；
-
發送“SpringCloud”領取cloud學習實戰資料；
