上周看到有人在我的Github開源項(xiàng)目中提了個(gè)issue，說是否考慮接入swagger。那今天我就用swagger與其他接口文檔工具做對(duì)比，同時(shí)說說Api接口文檔工具的那點(diǎn)事。如今，在前后端分離開發(fā)的這個(gè)年代，Api接口文檔管理工具越來越顯得重要。完整的Api接口文檔能大大提升前后端開發(fā)協(xié)作的效率。
目前市場(chǎng)有哪些比較優(yōu)秀的接口文檔管理工具呢？Swagger Api接口文檔工具到底如何，我大致匯總一下吧！
一、Swagger
說到Swagger，他確實(shí)是為開發(fā)者發(fā)明的一款神器，他可以實(shí)現(xiàn)自動(dòng)生成 API 接口文檔，在線調(diào)試，非常的方便。Swagger 官方文檔: https://swagger.io/。項(xiàng)目接入：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@EnableSwagger2public 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='根據(jù)Customer對(duì)象更新,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 代碼邏輯 }}啟動(dòng)項(xiàng)目，打開swagger,界面：http://192.168.1.101:9001/swagger-ui.html，
再看看剛配置的接口：
Swagger的接入特別簡(jiǎn)單，還可以在線調(diào)試。那么Swagger一定就很牛逼嗎，我們?cè)倏纯此膬?yōu)缺點(diǎn)。
Swagger的優(yōu)點(diǎn)如下：
1、節(jié)省了大量手寫接口文檔的時(shí)間，這是最大的優(yōu)勢(shì)；
2、生成的接口文檔可以直接在線測(cè)試，節(jié)省了使用Postman設(shè)置接口參數(shù)的過程，而且請(qǐng)求的參數(shù)，返回的參數(shù)一目了然；
3、接口按照模塊已經(jīng)分類展示，結(jié)構(gòu)清晰；
Swagger 的缺點(diǎn)****大致如下：
1、需要在代碼中寫大量的注解，生成的接口文檔越清晰，寫的注解越多；
2、對(duì)于復(fù)雜功能，一個(gè)功能需要多個(gè)模塊配合的情況下，聯(lián)調(diào)測(cè)試將會(huì)是一件非常麻煩的事。Swagger還不支持自定義接口文檔，不能指明某一個(gè)功能需要使用哪些接口；
3、對(duì)于返回結(jié)果不能添加說明或者實(shí)現(xiàn)這個(gè)功能非常麻煩。雖然 Swagger 有 @ApiResponse注解用來說明返回結(jié)果，但是這個(gè)使用并不方便，而且如果返回的并不是對(duì)象的時(shí)候(如 Map)，就無法實(shí)現(xiàn)給每一個(gè)返回字段的說明；
4、無法測(cè)試錯(cuò)誤的請(qǐng)求方式、參數(shù)等。如接口指定使用 POST 請(qǐng)求，則無法使用 swagger 測(cè)試 GET 請(qǐng)求的結(jié)果，也無法自定義 Header；
5，分布式開發(fā)環(huán)境中，一個(gè)項(xiàng)目往往有多個(gè)接口服務(wù)（比如電商項(xiàng)目有app，pc，后臺(tái)三個(gè)接口服務(wù)）。每一個(gè)接口服務(wù)都對(duì)應(yīng)一個(gè)獨(dú)立的swagger文檔，不能實(shí)現(xiàn)統(tǒng)一整合。
**二，apizza **
Apizza也是我們項(xiàng)目中使用過的，是從Swagger 轉(zhuǎn)到Apizza。而卻他是極客專屬的api協(xié)作管理工具，免費(fèi)的團(tuán)隊(duì)協(xié)作，在線模擬調(diào)試，快速生成api文檔，導(dǎo)出離線版文檔。
項(xiàng)目Api接入：
只需在Apizza官網(wǎng)（https://apizza.net）申請(qǐng)賬號(hào)，創(chuàng)建項(xiàng)目，并手寫添加接口文檔。
api跨域調(diào)試量身定制的chrome插件，本地，在線接口，都可以調(diào)。
云端存儲(chǔ)，企業(yè)安全版支持本地?cái)?shù)據(jù)中心。
一鍵分享，與團(tuán)隊(duì)共享你的API文檔。
支持Postman，Swagger格式 導(dǎo)入Postman/Swagger Json 生成文檔。
導(dǎo)出離線文檔，部署本地服務(wù)器。
api Mock 根據(jù)文檔自動(dòng)生成返回結(jié)果，提供獨(dú)立URL方便前端測(cè)試。
支持多種文檔 http接口文檔，markdown說明文檔。
Apizza接口文檔工具有一個(gè)很大不足的地方，那是Apizza個(gè)人免費(fèi)版有人數(shù)限制，所有超過8人的團(tuán)隊(duì)如果想免費(fèi)用，你是不用考慮Apizza的。如果你看到有文章或公眾號(hào)上說Apizza是免費(fèi)的，那簡(jiǎn)直是胡扯，他肯定沒用過。當(dāng)然如果你不缺錢，可以付費(fèi)開通企業(yè)版。我們團(tuán)隊(duì)也是用了半年多Apizza，后來由于人員增加，Apizza里又無法再新添加新成員，迫使我們不得不放棄Apizza。
三，Yapi
Yapi是去哪兒網(wǎng)開源的一款接口管理工具。Yapi旨意將接口作為一個(gè)公共的可視化的方式打通前端、后臺(tái)、測(cè)試環(huán)節(jié)，整合在一塊，共同使用維護(hù)，提高接口的維護(hù)成本。Yapi是一款免費(fèi)開源的Api接口文檔工具，需要下載部署在自己的服務(wù)器上。Yapi也是我們現(xiàn)在正在使用的接口文檔工具。
主要特點(diǎn)如下：
權(quán)限管理 YApi 成熟的團(tuán)隊(duì)管理扁平化項(xiàng)目權(quán)限配置滿足各類企業(yè)的需求；
可視化接口管理 基于 websocket 的多人協(xié)作接口編輯功能和類 postman 測(cè)試工具，讓多人協(xié)作成倍提升開發(fā)效率；
Mock Server 易用的 Mock Server，再也不用擔(dān)心 mock 數(shù)據(jù)的生成了；
自動(dòng)化測(cè)試 完善的接口自動(dòng)化測(cè)試,保證數(shù)據(jù)的正確性；
數(shù)據(jù)導(dǎo)入 支持導(dǎo)入 swagger, postman, har 數(shù)據(jù)格式，方便遷移舊項(xiàng)目；
插件機(jī)制 強(qiáng)大的插件機(jī)制，滿足各類業(yè)務(wù)需求；
這里關(guān)于Yapi的安裝就不詳細(xì)介紹了。Yapi安裝需事先安裝nodejs、mongodb、git應(yīng)用。今天主要講了我們使用過的Api接口文檔工具，整體來說，個(gè)人感覺這三款都不錯(cuò)。在團(tuán)隊(duì)很小的時(shí)候，實(shí)際那個(gè)都能滿足需求。但在團(tuán)隊(duì)人數(shù)慢慢增加時(shí)，就需要考慮一些工具的局限性，這也是我們從Swagger到Apizza再到Y(jié)api的原因。當(dāng)然，除了上面這三個(gè)，市面上還有很多其他的Api文檔工具。如：eoLinker、ShowDoc、easydoc、MinDoc等。說了這么多，那具體用哪一個(gè)呢？這需要根據(jù)自己的團(tuán)隊(duì)等情況選擇一款最適合自己的。
聯(lián)系客服
