上周看到有人在我的Github开源项目中提了个issue,说是否考虑接入swagger。那今天我就用swagger与其他接口文档工具做对比,同时说说Api接口文档工具的那点事。如今,在前后端分离开发的这个年代,Api接口文档管理工具越来越显得重要。完整的Api接口文档能大大提升前后端开发协作的效率。

image

目前市场有哪些比较优秀的接口文档管理工具呢?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

image

再看看刚配置的接口:

image

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文档,导出离线版文档。

image

项目Api接入:

只需在Apizza官网(https://apizza.net)申请账号,创建项目,并手写添加接口文档。

主要功能

  1. api跨域调试量身定制的chrome插件,本地,在线接口,都可以调。

  2. 云端存储,企业安全版支持本地数据中心。

  3. 一键分享,与团队共享你的API文档。

  4. 支持Postman,Swagger格式 导入Postman/Swagger Json 生成文档。

  5. 导出离线文档,部署本地服务器。

  6. api Mock 根据文档自动生成返回结果,提供独立URL方便前端测试。

  7. 支持多种文档 http接口文档,markdown说明文档。

Apizza接口文档工具有一个很大不足的地方,那是Apizza个人免费版有人数****限制,所有超过8人的团队如果想免费用,你是不用考虑Apizza的。如果你看到有文章或公众号上说Apizza是免费的,那简直是胡扯,他肯定没用过。当然如果你不缺钱,可以付费开通企业版。我们团队也是用了半年多Apizza,后来由于人员增加,Apizza里又无法再新添加新成员,迫使我们不得不放弃Apizza。

image

三,Yapi

Yapi是去哪儿网开源的一款接口管理工具。Yapi旨意将接口作为一个公共的可视化的方式打通前端、后台、测试环节,整合在一块,共同使用维护,提高接口的维护成本。Yapi是一款免费开源的Api接口文档工具,需要下载部署在自己的服务器上。Yapi也是我们现在正在使用的接口文档工具。

image

image

主要特点如下:

  • 权限管理 YApi 成熟的团队管理扁平化项目权限配置满足各类企业的需求;
  • 可视化接口管理 基于 websocket 的多人协作接口编辑功能和类 postman 测试工具,让多人协作成倍提升开发效率;
  • Mock Server 易用的 Mock Server,再也不用担心 mock 数据的生成了;
  • 自动化测试 完善的接口自动化测试,保证数据的正确性;
  • 数据导入 支持导入 swagger, postman, har 数据格式,方便迁移旧项目;
  • 插件机制 强大的插件机制,满足各类业务需求;

image

这里关于Yapi的安装就不详细介绍了。Yapi安装需事先安装nodejs、mongodb、git应用。今天主要讲了我们使用过的Api接口文档工具,整体来说,个人感觉这三款都不错。在团队很小的时候,实际那个都能满足需求。但在团队人数慢慢增加时,就需要考虑一些工具的局限性,这也是我们从Swagger到Apizza再到Yapi的原因。当然,除了上面这三个,市面上还有很多其他的Api文档工具。如:eoLinker、ShowDoc、easydoc、MinDoc等。说了这么多,那具体用哪一个呢?这需要根据自己的团队等情况选择一款最适合自己的。

扫码关注公众号,发送关键词获取相关资料:

  1. 发送“Springboot”领取电商项目实战源码;

  2. 发送“SpringCloud”领取cloud学习实战资料;

Api接口文档管理工具,你知道哪些呢?的更多相关文章

  1. api(接口)文档管理工具

    api(接口)文档管理工具 欢迎光临:博之阅API管理平台  ,做为一个app开发者,还没有用到api管理工具,你就OUT了 点击进入:程序员精华博客大全  

  2. api接口测试工具和接口文档管理工具

    api接口测试工具和接口文档管理工具 1.postman(https://www.getpostman.com) Postman 是一个很强大的 API调试.Http请求的工具.她可是允许用户发送任何 ...

  3. 接口文档管理工具-Postman、Swagger、RAP(转载)

    接口文档管理工具-Postman.Swagger.RAP 转自:http://www.51testing.com/html/10/n-3715910.html 在项目开发测试中,接口文档是贯穿始终的. ...

  4. 接口文档管理工具rap

    git地址:  https://github.com/thx/RAP wiki : https://github.com/thx/RAP/wiki/home_cn 视频教程: http://thx.g ...

  5. showdoc 开源在线api&&技术文档管理工具

    showdoc 是一个很不错的api 以及技术文档管理工具 环境准备 doker-copose 文件 version: "3" services: doc: image: regi ...

  6. RAP, 高效前后端联调框架,接口文档管理工具

    RAP通过GUI工具帮助WEB工程师更高效的管理接口文档,同时通过分析接口结构自动生成Mock数据.校验真实接口的正确性,使接口文档成为开发流程中的强依赖.有了结构化的API数据,RAP可以做的更多, ...

  7. .NET Core使用swagger进行API接口文档管理

    一.问题背景 随着技术的发展,现在的开发模式已经更多的转向了前后端分离的模式,在前后端开发的过程中,联系的方式也变成了API接口,但是目前项目中对于API的管理很多时候还是通过手工编写文档,每次的需求 ...

  8. 细说RESTful API之文档管理

    目录 API文档格式 文档管理方式 基于注解实现,代码和文档在一起 Swagger Api2Doc 基于API测试工具生成 Postman rest-client 独立编写文档 RAP DOCleve ...

  9. API文档管理工具

    系统庞大之后,前后端分离开发,前端调用后端提供的接口,请求协议一般是 HTTP,数据格式一般是 JSON.后台只负责数据的提供和计算,而完全不处理展现逻辑和样式:前端则负责拿到数据,组织数据并展现的工 ...

随机推荐

  1. PHP与ECMAScript_3_常用字符串函数

      PHP ECMAScript 长度 strlen($str) str.length     查找类 $str[n]                                          ...

  2. python传递参数

    1.脚本 # -*- coding: utf-8 -*- from sys import argvscript, first,second = argv #将命令中输入的参数解包后传递给左边 age ...

  3. python的enumerate lambda isinstance filter函数

    0x01:filter(function,iterable) filter()函数用于过滤序列,过滤掉不符合条件的元素,返回由符合条件元素组成的新列表. 接收两个参数,第一个为函数,第二个为序列(可迭 ...

  4. 关于FFT分析音频的学习

    本文部分知识从以下文章学习: https://zhuanlan.zhihu.com/p/19763358 傅里叶变换的知识 https://www.cnblogs.com/RabbitHu/p/FFT ...

  5. Mysql的行级锁与表级锁

    在计算机科学中,锁是在执行多线程时用于强行限制资源访问的同步机制,即用于在并发控制中保证对互斥要求的满足. 在DBMS中,可以按照锁的粒度把数据库锁分为行级锁(INNODB引擎).表级锁(MYISAM ...

  6. 【Java例题】6.1 进制转换

    1.进制转换.输入一个某种进制的整数,将其转换为其它进制的整数.说明:仅考虑十.二.八和十六进制. package chapter6; import java.util.*; public class ...

  7. spring-boot-starter-quartz集群实践

    [**前情提要**]由于项目需要,需要一个定时任务集群,故此有了这个spring-boot-starter-quartz集群的实践.springboot的版本为:2.1.6.RELEASE:quart ...

  8. 你真的了JMeter解聚合报告么?

    1.背景 大家在使用JMeter进行性能测试时,聚合报告(Aggregate Report)可以说是必用的监听器,但是你真的了解聚合报告么? 2.目的 本次笔者跟大家聊聊聚合报告(Aggregate ...

  9. print,cat打印格式及字符串引号格式,去掉字符串空格 in R

    print 函数的打印格式: ##no quote print out > x <- letters[1:5] > print(x,quote=F,);print(x,quote=T ...

  10. Mybatis框架(9)---Mybatis自定义插件生成雪花ID做为表主键项目

    Mybatis自定义插件生成雪花ID做为主键项目 先附上项目项目GitHub地址 spring-boot-mybatis-interceptor 有关Mybatis雪花ID主键插件前面写了两篇博客作为 ...