api文档调研

一、为什么需要接口文档管理

  1. 文档过时,与接口不同步
  2. 工作不能并行
  3. 应用界面和接口强耦合难分离
  4. 版本迭代导致大量重复功能的接口
  5. 前端、客户端、后端扯皮

二、API文档是什么?

  • API : (Application Programming Interface) , 即应用程序编程接口。
  • API文档:是API的说明文档,是一个规范的、明确的接口说明书,详细的描述了每个接口的作用、入参、出参、返回值等等。

行业中的选择:

Apizza、易文档、Yapi、ApiDoc、JApiDocs、postman、RAP2、swagger、eolinker......

 

各方案的优缺点:

 

 

Apizza http://apizza.cc/

apizza的定位是api协作管理工具

优点:

中文界面、有一定用户群、上手成本低、多种格式、团队协作、一键生成文档

支持导出离线文档

缺点:

收费,需要浏览器安装插件

 

易文档 https://easydoc.xyz

易文档的定位是简洁好用的在线文档工具

优点:

中文界面、有一定用户群、上手成本低、多种文档格式、团队协作

支持导出离线文档

缺点:

收费、需要浏览器插件

 

YApi https://easydoc.xyz https://github.com/YMFE/yapi

YApi旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 API

优点:

开源易部署、中文界面、用户多、权限管理、自动化测试、导入导出、

多种文档格式、团队协作、支持导出离线文档

缺点:

需要浏览器插件、只能内网部署、依赖mongodb、node.js

 

apiDoc https://apidocjs.com/ https://github.com/apidoc/apidoc

apizza的定位是一个非常轻量级的Restful API的文档自动生成工具。

apiDoc通过源代码中的API注释创建文档。

优点:

开源、自动生成

缺点:

注释侵入,格式单一、不支持导入导出

 

JApiDocs https://github.com/YeDaxia/JApiDocs

优点:

开源、代码即文档,学习和维护成本低、项目集成

缺点:

只支持Java、测试发布到RAP、

 

 

Postman https://www.getpostman.com/

行业标杆 基本其他各类api工具到在模仿或者兼容postman

优点:

门槛低、上手快、跨平台、支持抓包、历史记录、导入导出、团队协作

监控器、自动化测试、

缺点:

收费、云服务服务器存储、英文界面

 

RAP2 http://rap2.taobao.org/ https://github.com/thx/rap2-delos

提供方便的接口文档管理、Mock、导出等

优点:

开源、团队协作、历史记录、权限管理、多种格式、

支持离线文档

缺点:

部署难度高、依赖多(nodejs、MySQL、Redis、pandoc)、据说容易崩

 

swagger

优点:

开源、代码读取生成api,集成简单、用户多、接口测试

缺点:

代码侵入、不支持离线文档

 

eolinker

优点:

中文界面、团队协作、权限管理,支持离线文档,完整的商业化的接口管理工具、接口测试

支持导出离线文档

缺点:

收费

 

 

Swagger

Swagger:是一个工具、一组开源项目、一个流行的API开发框架

这个框架以OAS为基础,对整个API的开发周期都提供了相应的解决方案,是一个非常庞大的项目(包括Swagger Editor、Swagger UI、Swagger Codegen、Swagger Inspector)。

Swagger Editor

REST APIs文档生成工具

Swagger Codegen

根据编辑完成的Swagger API文档文件生成代码的工具

Swagger UI

API文档可视化工具

Swagger Inspector

API测试工具

 

Springfox:

Springfox是践行OAS的一个项目,它将Swagger融合进流行的Spring框架,根据OpenAPI规范,帮助开发者自动生成API文档。Springfox是由Marty Pitt创建的项目swagger-springmvc发展而来。它其中有一个组件叫springfox-swagger2,springfox-swagger2是依赖OSA规范文档,也就是一个描述API的json文件,而这个组件的功能就是帮助我们自动生成这个json文件,我们会用到的另外一个组件springfox-swagger-ui就是将这个json文件解析出来,用一种更友好的方式呈现出来。

首先定义了一个API文档产生的规范,前期叫Swagger,后面贡献给了Linux基金会,逐渐演变成OpenAPI Specification,逐渐成为世界级别的规范,即OAS,它定义了一种JSON格式或者YAML格式的API文档文件格式;而Swagger提供了Swagger Editor来帮助开发人员熟悉和编写正确的符合OpenAPI规范的API文档文件,这个文件可以使JSON格式的,也可以是YAML格式的;Swagger又提供了Swagger Codegen来生成API文档对应的代码,Swagger Codegen来展示API文档,Swagger Inspector来测试API对应的代码;最后Springfox结合Spring与Swagger,帮助开发人员自动生成对应代码的对应API。

 

swagger生态图

 

其中,红颜色的是swaggger官网方推荐的。

 

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值