代碼未動，文檔先行

其实大家都知道 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. 接口自動化測試：提供接口集合測試，可以通过选择接口（或接口用例）快速创建测试集。目前接口自動化測試更多功能还在开发中，敬请期待！目标是： JMeter 有的功能基本都会有，并且要更好用。
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的string类型字段，自动 mock 出一个图片地址 URL；包含字符串time的string类型字段，自动 mock 出一个时间字符串；包含字符串city的string类型字段，自动 mock 出一个城市名。
3. Apifox 根据内置规则，可自动识别出图片、头像、用户名、手机号、网址、日期、时间、时间戳、邮箱、省份、城市、地址、IP 等字段，从而 Mock 出非常人性化的数据。
4. 除了内置 mock 规则，用户还可以自定义规则库，满足各种个性化需求。支持使用 正則表達式、通配符 来匹配字段名自定义 mock 规则。

8、生成在线接口文檔

Apifox 项目可“在线分享” API 文档，分享出去的 API 文档可设置为公开或需要密码访问，非常方便与外部團隊協作。

體驗地址：https://www.apipark.cn/s/ce387612-cfdb-478a-b604-b96d1dbc511b/http/5041285

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. 支持离线使用，项目可选择在线同步（團隊協作）还是仅本地存储（单机离线使用）。

四、更多 Apifox 功能截图

五、 Apifox 下载地址

軟件完全免費，複制下面的鏈接，粘貼到浏覽器打開即可下載。
官網地址：www.apifox.cn