上周看到有人在我的Github開(kāi)源項(xiàng)目中提了個(gè)issue，說(shuō)是否考慮接入swagger。那今天我就用swagger與其他接口文檔工具做對(duì)比，同時(shí)說(shuō)說(shuō)Api接口文檔工具的那點(diǎn)事。如今，在前后端分離開(kāi)發(fā)的這個(gè)年代，Api接口文檔管理工具越來(lái)越顯得重要。完整的Api接口文檔能大大提升前后端開(kāi)發(fā)協(xié)作的效率。

image

目前市場(chǎng)有哪些比較優(yōu)秀的接口文檔管理工具呢？Swagger Api接口文檔工具到底如何，我大致匯總一下吧！

一、Swagger

說(shuō)到Swagger，他確實(shí)是為開(kāi)發(fā)者發(fā)明的一款神器，他可以實(shí)現(xiàn)自動(dòng)生成 API 接口文檔，在線調(diào)試，非常的方便。Swagger 官方文檔: https:///。項(xiàng)目接入：pom依賴：

配置信息：

@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里的配置（例如）：

啟動(dòng)項(xiàng)目，打開(kāi)swagger,界面：http://192.168.1.101:9001/swagger-ui.html，

image

再看看剛配置的接口：

image

Swagger的接入特別簡(jiǎn)單，還可以在線調(diào)試。那么Swagger一定就很牛逼嗎，我們?cè)倏纯此膬?yōu)缺點(diǎn)。

Swagger的優(yōu)點(diǎn)如下：

1、節(jié)省了大量手寫(xiě)接口文檔的時(shí)間，這是最大的優(yōu)勢(shì)；

2、生成的接口文檔可以直接在線測(cè)試，節(jié)省了使用Postman設(shè)置接口參數(shù)的過(guò)程，而且請(qǐng)求的參數(shù)，返回的參數(shù)一目了然；

3、接口按照模塊已經(jīng)分類展示，結(jié)構(gòu)清晰；

Swagger 的缺點(diǎn)****大致如下：

1、需要在代碼中寫(xiě)大量的注解，生成的接口文檔越清晰，寫(xiě)的注解越多；

2、對(duì)于復(fù)雜功能，一個(gè)功能需要多個(gè)模塊配合的情況下，聯(lián)調(diào)測(cè)試將會(huì)是一件非常麻煩的事。Swagger還不支持自定義接口文檔，不能指明某一個(gè)功能需要使用哪些接口；

3、對(duì)于返回結(jié)果不能添加說(shuō)明或者實(shí)現(xiàn)這個(gè)功能非常麻煩。雖然 Swagger 有 @ApiResponse注解用來(lái)說(shuō)明返回結(jié)果，但是這個(gè)使用并不方便，而且如果返回的并不是對(duì)象的時(shí)候(如 Map)，就無(wú)法實(shí)現(xiàn)給每一個(gè)返回字段的說(shuō)明；

4、無(wú)法測(cè)試錯(cuò)誤的請(qǐng)求方式、參數(shù)等。如接口指定使用 POST 請(qǐng)求，則無(wú)法使用 swagger 測(cè)試 GET 請(qǐng)求的結(jié)果，也無(wú)法自定義 Header；

5，分布式開(kāi)發(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)目中使用過(guò)的，是從Swagger 轉(zhuǎn)到Apizza。而卻他是極客專屬的api協(xié)作管理工具，免費(fèi)的團(tuán)隊(duì)協(xié)作，在線模擬調(diào)試，快速生成api文檔，導(dǎo)出離線版文檔。

image

項(xiàng)目Api接入：

只需在Apizza官網(wǎng)（https://）申請(qǐng)賬號(hào)，創(chuàng)建項(xiàng)目，并手寫(xiě)添加接口文檔。

主要功能

1. api跨域調(diào)試量身定制的chrome插件，本地，在線接口，都可以調(diào)。

2. 云端存儲(chǔ)，企業(yè)安全版支持本地?cái)?shù)據(jù)中心。

3. 一鍵分享，與團(tuán)隊(duì)共享你的API文檔。

4. 支持Postman，Swagger格式 導(dǎo)入Postman/Swagger Json 生成文檔。

5. 導(dǎo)出離線文檔，部署本地服務(wù)器。

6. api Mock 根據(jù)文檔自動(dòng)生成返回結(jié)果，提供獨(dú)立URL方便前端測(cè)試。

7. 支持多種文檔 http接口文檔，markdown說(shuō)明文檔。

Apizza接口文檔工具有一個(gè)很大不足的地方，那是Apizza個(gè)人免費(fèi)版有人數(shù)限制，所有超過(guò)8人的團(tuán)隊(duì)如果想免費(fèi)用，你是不用考慮Apizza的。如果你看到有文章或公眾號(hào)上說(shuō)Apizza是免費(fèi)的，那簡(jiǎn)直是胡扯，他肯定沒(méi)用過(guò)。當(dāng)然如果你不缺錢(qián)，可以付費(fèi)開(kāi)通企業(yè)版。我們團(tuán)隊(duì)也是用了半年多Apizza，后來(lái)由于人員增加，Apizza里又無(wú)法再新添加新成員，迫使我們不得不放棄Apizza。

image

三，Yapi

Yapi是去哪兒網(wǎng)開(kāi)源的一款接口管理工具。Yapi旨意將接口作為一個(gè)公共的可視化的方式打通前端、后臺(tái)、測(cè)試環(huán)節(jié)，整合在一塊，共同使用維護(hù)，提高接口的維護(hù)成本。Yapi是一款免費(fèi)開(kāi)源的Api接口文檔工具，需要下載部署在自己的服務(wù)器上。Yapi也是我們現(xiàn)在正在使用的接口文檔工具。

image

image

主要特點(diǎn)如下：

• 權(quán)限管理 YApi 成熟的團(tuán)隊(duì)管理扁平化項(xiàng)目權(quán)限配置滿足各類企業(yè)的需求；

• 可視化接口管理 基于 websocket 的多人協(xié)作接口編輯功能和類 postman 測(cè)試工具，讓多人協(xié)作成倍提升開(kāi)發(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ù)需求；

image

這里關(guān)于Yapi的安裝就不詳細(xì)介紹了。Yapi安裝需事先安裝nodejs、mongodb、git應(yīng)用。今天主要講了我們使用過(guò)的Api接口文檔工具，整體來(lái)說(shuō)，個(gè)人感覺(jué)這三款都不錯(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等。說(shuō)了這么多，那具體用哪一個(gè)呢？這需要根據(jù)自己的團(tuán)隊(duì)等情況選擇一款最適合自己的。