先写API文档仍是先写代码？你需求这款神器！

代码未动，文档先行

其实咱们都知道 API 文档先行的重要性，可是在实践进程中往往会遇到许多困难。

程序员最厌烦的两件事：1. 写文档，2. 他人不写文档。大多数开发人员不愿意写 API 文档的原因是写文档短期收益远低于支付的本钱，可是并不是一切人都能够坚持做有长时刻收益的作业的。

作为一个前后端别离形式开发的团队，咱们常常会看到这样的场景：前端开发和后端开发在一同火热的评论“你这接口参数怎样又变了？”，“接口怎样又不通了？”，“稍等，我调试下”，“你再试试..."。

那能不能写好 API 文档，咱们都按文档来开发？很难，由于写文档、保护文档比较费事，而且费时，还会常常出现 API 更新了，但文档仍是旧的，各种同步不一致的状况，然后耽误互相的时刻。

之前咱们团队也遇到了相同的问题，那么作为研制团队的负责人，我是怎么带领团队处理这个问题的呢？

怎么做？

办法其实很简单，假如能做到让写文档/保护文档这件作业的短期收益就能远高于支付的本钱，那么一切问题都能便利的处理，开发人员就会十分愿意去写接口文档。

团队本来的作业形式

1. API 规划人员运用 Swagger 写 API 文档
2. 前端开发 运用 mock.js  mock 假的 API 数据
3. 后端开发 运用 Postman 调试 API
4. 测验人员 运用 JMeter 测验 API

咱们遇到的问题

1. 咱们团队是前后端同步进入开发的，不能等后端开发完了才出接口文档，前端再进入开发，所以运用后端代码注释主动生成 Swagger 不适合咱们。
2. 写 Swagger 文档功率很低，而且有学习门槛，让团队一切人都娴熟手写 Swagger 文档是不现实的，更何况团队不断有新人进来。
3. 开发人员在 Swagger 界说好文档后，接口调试的时分还需求去 Postman 再界说一遍。
4. 前端开发 Mock 数据的时分又要去 mock 东西里界说一遍，手动设置好 Mock 规矩。
5. 测验人员需求去 JMeter 界说一遍。
6. 前端依据 mock 东西出来的数据开发完，后端依据 Swagger 界说的接口文档开发完，各自测验测验经过了，本以为能够立刻上线，成果一对接发现各种问题：本来开发进程中接口改变，只修正了 Swagger，可是没有及时同步修正 mock。
7. 相同，测验在 JMeter 写好的测验用例，真实运转的时分也会发现各种不一致。
8. 开发进程，常常会有发现开端界说的接口文档有不合理的当地，需求暂时调整，常常出现接口改了，可是文档没有更新。
9. 时刻久了，各种不一致会越来越严峻。

怎么处理

要做到写文档和及时保护文档的短期收益就能远高于支付的本钱，无非两个方向：

1. 下降写文档的本钱
2. 增加写文档后的收益

鉴于此，咱们想象假如有一款东西做到以下这些是不是就十分爽了？

1. 以彻底可视化的界面来编写文档，而且是零学习本钱，新人 一来就能上手。
2. 能够经过接口文档界说的数据结构主动 mock出数据，而无需 前端开发 再写mock规矩，直接开工。
3. 后端开发 在接口文档基础上调试接口，而无需在去Postman上调试；接口如有改变，调试的时分就主动更新了文档，零本钱的确保了接口保护的及时性；主动依据文档校验数据结构，无需肉眼校验，无需手动写断语。
4. 后端开发 每次调试完一个功用就保存为一个接口用例。
5. 测验人员 直接运用接口用例测验接口。
6. 测验人员 愈加接口文档主动生成测验用例，然后像JMeter相同在直接在上面测验。
7. 依据接口文档界说的数据结构，主动生成前后端的数据模型代码。

总结下来，咱们需求的便是这么一款东西：

经过一套体系、一份数据，处理多个体系之间的数据同步问题。只需界说好接口文档，接口调试、数据 Mock、接口测验就能够直接运用，无需再次界说；接口文档和接口开发调试运用同一个东西，接口调试完结后即可确保和接口文档界说彻底一致。高效、及时、精确！

为此，咱们简直尝遍了市面上一切相关的东西，可是很惋惜，没有找到适宜的。

怎样办？自己干！

所以，咱们自己完结了一个Postman + Swagger + Mock + JMeter

这个东西便是 Apifox，常常很长一段时刻不断更新迭代后，咱们基本上彻底完结了开端的想象，简直完美处理了最开端遇到的一切问题，在公司内部大受欢迎。而且也形成了咱们自己的最佳实践。

最佳实践

1. 前端（或后端）在 Apifox 上定好接口文档初稿。
2. 前后端 一同评定、完善接口文档，定好接口用例。
3. 前端 运用 Apifox 主动生成的 Mock 数据进入开发，而无需手写mock规矩，直接开工。
4. 后端 运用接口用例 调试开发中接口，体系依据接口文档的界说主动校验回来的数据是否正确，只需一切接口用例调试经过，接口就开发完结了。
5. 后端 开发完结后，测验人员（也能够是后端）运用调集测验功用进行多接口集成测验，完好测验整个接口调用流程。
6. 前后端 都开发完，前端从Mock 数据切换到正式数据，联调一般都会十分顺畅，由于前后端两边都彻底恪守了接口界说的标准。

Apifox 处理方案

一、怎么处理这些问题

1、Apifox 定位

Apifox = Postman + Swagger + Mock + JMeter

Apifox 是 API 文档、API 调试、API Mock、API 主动化测验一体化协作渠道。

经过一套体系、一份数据，处理多个体系之间的数据同步问题。只需界说好接口文档，接口调试、数据 Mock、接口测验就能够直接运用，无需再次界说；接口文档和接口开发调试运用同一个东西，接口调试完结后即可确保和接口文档界说彻底一致。高效、及时、精确！

2、Apifox 主旨

节约研制团队的每一分钟！

3、Apifox 功用

1. 接口规划：Apifox 接口文档遵从 OpenApi 3.0 (原 Swagger)、JSON Schema 标准的一起，供给了十分好用的可视化
2. 数据模型：可复用的数据结构，界说接口回来数据结构及恳求参数数据结构（仅 JSON 和 XML 形式）时可直接引证。支撑模型直接嵌套引证，直接 JSON/XML 智能导入，支撑 oneOf、allOf 等高档组合形式。
3. 接口调试：Postman 有的功用，比方环境变量、前置/后置脚本、Cookie/Session 大局同享 等功用，Apifox 都有，而且比 Postman 更高效好用。接口运转完之后点击保存为用例按钮，即可生成接口用例，后续可直接运转接口用例，无需再输入参数，十分便利。自界说脚本 100% 兼容 Postman 语法，而且支撑运转javascript、java、python、php、js、BeanShell、go、shell、ruby、lua等各种言语代码。
4. 接口用例：一般一个接口会有多种状况用例，比方参数正确用例、参数过错用例、数据为空用例、不同数据状况用例等等。运转接口用例时会主动校验数据正确性，用接口用例来调试接口十分高效。
5. 接口数据 Mock：内置 Mock.js 规矩引擎，十分便利 mock 出各种数据，而且能够在界说数据结构的一起写好 mock 规矩。支撑增加“希望”，依据恳求参数回来不同 mock 数据。最重要的是 Apifox 零装备 即可 Mock 出十分人性化的数据，详细在本文后边介绍。
6. 数据库操作：支撑读取数据库数据，作为接口恳求参数运用。支撑读取数据库数据，用来校验(断语)接口恳求是否成功。
7. 接口主动化测验
8. 便利调试：相似 Postman 的接口调试方法，主要用途为暂时调试一些无需文档化的接口，无需提早界说接口即可快速调试。
9. 代码生成：依据接口及数据数据模型界说，体系主动生成接口恳求代码、前端事务代码及后端事务代码。
10. 团队协作：Apifox 天然生成便是为团队协作而生的，接口云端实时同步更新，老练的团队/项目/成员权限办理，满意各类企业的需求。

二、Apifox 做的不仅仅是数据打通

假如你以为 Apifox 只做了数据打通，来提高研制团队的功率，那就错了。Apifox 还做了十分多的立异，来提高开发人员的功率。

1、接口支撑“用例办理”

一般一个接口会有多种状况用例，比方 正确用例 参数过错用例 数据为空用例 不同数据状况用例。界说接口的时分界说好这些不同状况的用例，接口调试的时分直接运转，十分高效。

2、“数据模型”界说、引证

能够独立界说数据模型，接口界说时能够直接引证数据模型，数据模型之间也能够彼此引证。相同的数据结构，只需求界说一次即可多处运用；修正的时分只需求修正一处，多处实时更新，防止不一致。

3、调试时“主动校验”数据结构

运用 Apifox 调试接口的时分，体系会依据接口文档里的界说，主动校验回来的数据结构是否正确，无需经过肉眼辨认，也无需手动写断语脚本检测，十分高效！

4、“可视化”设置断语

设置断语：

运转后，检查断语成果：

5、“可视化”设置提取变量

6、支撑数据库操作

7、“零装备”Mock 出十分人性化的数据

先放一张图比照下 Apifox 和其他同类东西 零装备 mock 出来的数据作用：

能够看出 Apifox 零装备 Mock 出来的数据和真实状况是十分挨近的，前端开发能够直接运用，而无需再手动写 mock 规矩。

Apifox 怎么做到高功率、零装备生成十分人性化的 mock 数据

1. Apifox 依据接口界说里的数据结构、数据类型，主动生成 mock 规矩。
2. Apifox 内置智能 mock 规矩库，依据字段名、字段数据类型，智能优化主动生成的 mock 规矩。如：称号包括字符串image的stringtime的string类型字段，主动 mock 出一个时刻字符串；包括字符串city的string类型字段，主动 mock 出一个城市名。
4. 除了内置 mock 规矩，用户还能够自界说规矩库，满意各种个性化需求。支撑运用 正则表达式、通配符 来匹配字段名自界说 mock 规矩。

8、生成在线接口文档

9、代码主动生成

依据接口模型界说，主动生成各种言语/结构（如 TypeScript、Java、Go、Swift、ObjectiveC、Kotlin、Dart、C++、C#、Rust 等）的事务代码（如 Model、Controller、单元测验代码等）和接口恳求代码。现在 Apifox 支撑 130 种言语及结构的代码主动生成。

更重要的是：你能够经过来生成契合自己团队的架构标准的代码，满意各种个性化的需求。

10、导入、导出

1. 支撑导出 OpenApi (Swagger)、Markdown、Html 等数据格局，由于能够导出OpenApi格局数据，所以你能够运用 OpenApi (Swagger) 丰厚的生态东西完结各种接口相关的作业。
2. 支撑导入 OpenApi (Swagger)、Postman、HAR、RAML、RAP2、YApi、Eolinker、NEI、DOClever、ApiPost 、Apizza 、ShowDoc、API Blueprint、I/O Docs、WADL、Google Discovery等数据格局，便利旧项目搬迁。

三、后续功用规划

1. 发布 Apifox WEB 版，支撑在浏览器端运用 Apifox。
2. 接口功用测验支撑（相似 JMeter）。
3. 支撑插件商场，能够自己开发插件。
4. 敞开 Apifox API，答应开发者经过 API 调用 Apifox 的功用。
5. GraphQL、gRPC、websocket等。
6. 支撑离线运用，项目可选择在线同步（团队协作）仍是仅本地存储（单机离线运用）。