如何优雅的进行接口管理

在这前后端分离大行其道的今天，如何优雅的管理接口，对应提高工作效率非常重要。而接口又是由后端提供的，这个任务自然而然的又落在后台开发人员的身上。在这里提供三种常见的接口管理方案，这三种方案没有属谁最优，属谁最差。根据项目的情况而定。

0x01：基于文档式的接口管理

基于文档式的接口管理时最传统，也是最常见的接口管理方式。因为一直做些不大不小的项目型项目，所以几乎使用的都是该接口管理方案。文档格式多种多样，常见的文档格式有：

• 电子表格Execl

• 电子文档Word

• PDF文件

这三种文档格式，用于管理接口，小编使用 Execl 最为顺手。大致模板如下：

接口目录

image.png

接口详情

image.png

这种方案比较难控制版本，每次修改接口时，都需要同步更新接口文档。否则就造成接口与接口文档不一致。

0x02：内嵌接口服务

把在线接口文档内嵌到应用服务里，最流行的当属 Swagger 框架。Swagger 框架与Spring 框架完美集合，使用非常方便。

Swagger 是一个大型的 AP I开发者的工具框架，该框架提出了一个编写 OpenAPI的规范（命名为 OA S），并且 Swagger 可以跨整个 API 生命周期进行开发，从设计和文档到测试和部署。Swagger 框架有三大核心部分：

• 提供了一个编写 API 文档的规范 ，称为 OAS ，在规范中明确API的格式和一些编写要素；

• 提供相关的工具，对 API 文档的编写提供辅助。主要是这么几个项目 Swagger Editor、SwaggerUI、Swagger Codegen、Swagger Inspector；

• 提供对各种流行语言和框架的集成，例如，集成 SpringMVC 的 springfox 框架；

  
  
  image.png

这种方案只要把 Swagger 集成到项目中，然后按照规范添加相关的注解；启动服务，访问响应地址，就可以看到接口文档 了。但是因为接口文档嵌入到应用服务中，所以生产部署一定要考虑安全问题，防止线上的接口裸奔，被不法人员利用，给公司造成损失。

0x03：独立接口平台

现在越来越多的公司提供开放平台，所以独立接口平台变得越来越常见了。比如，微信公众平台接口文档、微信小程序接口文档。

image.png

这种方案有非常多的选择方案。

• YApi（去哪儿出品）

仓库地址：

https://github.com/cklwblove/yapi

YApi 是高效、易用、功能强大的 api 管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。它可以帮助开发者轻松创建、发布、以及维护API。除此之外，YApi 还为用户提供了优秀的交互体验，开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。

• ShowDoc （收费）

ShowDoc 一个非常适合IT团队的在线 API 文档、技术文档工具。随着移动互联网的发展，BaaS（后端即服务）越来越流行。服务端提供 API，APP 端或者网页前端便可方便调用数据。用 ShowDoc 可以非常方便快速地编写出美观的API文档。

image.png

演示地址：

https://www.showdoc.com.cn/demo

• RAP / rap2-delos + rap2-dolores（阿里出品）

   阿里妈妈前端团队出品的开源接口管理工具 RAP 第二代，RAP 通过 GUI 工具帮助 WEB 工程师更高效的管理接口文档，同时通过分析接口结构自动生成 Mock 数据、校验真实接口的正确性，使接口文档成为开发流程中的强依赖。有了结构化的 API 数据，RAP 可以做的更多，而我们可以避免更多重复劳动。基于 RAML 的接口定义、文档生成、Mock Server 完成了定义和使用的分离，通过一套规范完成的接口定义，可以用不同的工具得到适应不同API管理系统的输出，有更多的可能性，同时保持了核心定义不变。RAP 较之于 RAML，前者更加集中，所有的定义、文档、mock 都在同一个服务中完成，并且实时生效，方便快捷，如果只考虑方便易用，RAP 是更好的选择，而 RAML 显得更加繁琐，更适合于公开的接口定义，方便在各个系统之间流转。
  

image.png

演示地址：

http://rap2.taobao.org/

仓库地址：

https://github.com/thx/rap2-delos

RAP 目前有两个版本，第一个版本的 RAP 已经被官方废弃了，建议用第二个版本。RAP2 分成了两个包：

• rap2-delos：后端数据 API 服务器

• rap2-dolores：前端静态资源