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官网方推荐的。