携手创作，共同成长！这是我参与「掘金日新计划 · 8 月更文挑战」的第26天，点击查看活动详情
概述
根据调研显示，围绕API相关的开发基本占用整体开发的50%左右时间。另一方面，随着公司架构的升级，各个组件微服务化，模块之间调用变的复杂，所以API的研发管理变得极为关键。目前公司接口的管理很不规范，有的后端通过swagger发给前端，有的后端直接通过文档发给前端，没有统一的接口管理工具。
在对比了市面上已有的接口管理平台，比如Apifox, Apipost, Yapi等，我们最终选择了Yapi，相比于Apifox等迭代迅速，功能齐全的商业化产品，Yapi最大的优势就是开源，免费，而且基本上能够满足我们如下的目标：
- 统一的可视化接口管理，后端、前端、测试能够及时的看到接口，减少依赖
- 简易的数据mock，让前端再也不等在那里了
- 自动化接口测试工具，可供后端进行接口自测
- 数据导入导出，方便接口的维护
YAPI产品介绍和使用
github地址：
YApi 是高效、易用、功能强大的 api 管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 API，YApi 还为用户提供了优秀的交互体验，开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。
基本使用：
yapi.smart-xwork.cn/doc/documen…
接口工作流程
公司采用敏捷迭代的开发流程，在敏捷迭代的开发周期中，YAPI如何参与进行接口管理工作？后端人员、前端人员以及测试该如何协同工作，形成高效、敏捷、简单的接口工作流？
后端人员
- 上一个迭代周四周五和前端同事进行概要设计，根据需求确定新增修改的接口，包括请求类型、入参格式、出参格式等，最重要的是约定好接口联调的时间点。
- 迭代第一周的周一，发布接口到YAPI中，并且通知对应的前端同事验收。如何发布接口，请看下面的最佳实践。
- 接口需要在YAPI上打上标签，标记是哪个迭代
- 接口需要在YAPI上标记是否是外部接口
- 迭代开发过程中，接口尽量不做改动，需要在概要设计阶段尽量细化。如果实在进行变更，需要通知对应的前端人员，同时发送钉钉机器人变动。
- 和前端接口联调前，需要在YAPI中添加接口的测试用例，执行通过，表明接口自测通过，具体如何操作见下面的最佳实践。
前端人员
- 前端人员在上一个迭代周四周五和后端同时进行概要设计，确定接口格式，并且约定好接口联调的时间点。
- 迭代第一周周一，前端人员根据接口规范在YAPI上审核接口是否满足要求。
- 迭代开发过程中，前端人员需要留一下接口是否发生变化。
- 前端人员开始接口联调时，首先查看对应接口是否存在测试用例，不存在则拒绝联调。
测试人员
- 测试人员可以在YAPI中查看迭代的接口，进行接口测试用例编写。
一些最佳实践（Q&A)
如何发布接口到YAPI？
发布接口到YAPI的方式主要有下面3种：
- 通过swagger同步
- 添加swagger注解，controller上面的tags建议使用模块名称，因为他会被解析成yapi的分类，不然yapi的分类很多。
- 接口上添加swagger注解，tags上补充变化的版本
- 通过数据导入导出，导入swagger
- 页面手动添加接口
通过界面添加接口。
- 通过idea插件发布
- idea安装EasyYapi插件
- 选中接口，发布到yapi中，发布到yapi的注释信息是根据javadoc生成的，所以要完善javadoc
- 发布过程中，需要设置项目的token, token获取如下：
我们建议使用第一种方式。
如何设置钉钉机器人发布接口变更？
- 钉钉群添加机器，设置过滤的关键词， 比如接口文档所属项目的项目名称sdm
- 项目设置标签
- 发生变化收到通知
如何设置对外接口并且导出？
- 如果接口是对其他组件服务暴露的接口，设置接口的为开放接口。
- 导出开放接口
- 查看开放接口
如何查看当前迭代的接口？
- 后端同事需要为接口打上标签
- 前端同事根据标签过滤迭代的接口
如何进行接口测试？
- 后端开发添加环境配置
- 后端执行测试用例
- 保存用例
- 前端同事检查用例，开始联调
什么是好的接口格式规范？
其实在我们的场景里，就是YAPI中哪些元素必须要写清楚。
- 请求参数中必须写清楚参数的含义，是否必填等
- 请求参数只需要显示接口实际需要的参数，不需要的不要展示，以防混淆。
- 返回报文必须写清楚字段的含义，返回类等
- 返回报文尽量不要返回无需使用的字段，以防混淆，也不符合良好的设计规范。
- 尽量写下备注，表明接口的实现逻辑，使用的注意事项，tps等。
