一、为什么需要接口文档管理
- 文档过时,与接口不同步
- 工作不能并行
- 应用界面和接口强耦合难分离
- 版本迭代导致大量重复功能的接口
- 前端、客户端、后端扯皮
二、API文档是什么?
- API : (Application Programming Interface) , 即应用程序编程接口。
- API文档:是API的说明文档,是一个规范的、明确的接口说明书,详细的描述了每个接口的作用、入参、出参、返回值等等。
行业中的选择:
Apizza、易文档、Yapi、ApiDoc、JApiDocs、postman、RAP2、swagger、eolinker......
各方案的优缺点:
Apizza http://apizza.cc/
apizza的定位是api协作管理工具
优点:
中文界面、有一定用户群、上手成本低、多种格式、团队协作、一键生成文档
支持导出离线文档
缺点:
收费,需要浏览器安装插件
易文档的定位是简洁好用的在线文档工具
优点:
中文界面、有一定用户群、上手成本低、多种文档格式、团队协作
支持导出离线文档
缺点:
收费、需要浏览器插件
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官网方推荐的。