为什么开发人员都不愿意写接口文档？

[falcon05]

你愿意写吗？

[balabalaguguji]

因为太麻烦了，不过可以借助一些比较方便的工具来写 https://easydoc.net

[securityCoding]

基本都在用 swagger 标准化了，不存在写不写的问题

[AoEiuV020]

开发的时候很多不确定，写了可能要改，
开发完了，都已经能用了还写什么文档，而且下个任务来了，也没时间，

[aaniao002]

@AoEiuV020 up，深入灵魂的回答。

[Building]

现在编程语言关键字一个比一个多，命名一个比一个长，你觉得是为了什么？显得高级吗？

[CEBBCAT]

我最讨厌写文档以及别人不写文档！

我写一个接口文档可能就要写半天，要先写 demo，再写行为，再写异常 case 下的行为，还要调得漂漂亮亮的，唉，做人难，做开发，更难

[yuandj]

推荐 ApiPost 接口联调工具，可以多人协作，自己进行接口测试时，就可以生成文档发布

[silencil]

文档是对我代码可读性的侮辱(手动狗头🐶)

[IvanLi127]

愿意写接口文档的路过。。。

[silencil]

正经回答其实上面已经说了，如 Java，关键的代码抽成方法，命名体现功能，各方面规范些再加上 Java 代码的可读性，整体来说我觉的已经足够替代文档了。真正需要的文档应该是需求文档，设计文档。

[dqzcwxb]

我哪是不想写文档,我压根就不想工作

[bojackhorseman]

@dqzcwxb 真相了

[cmdOptionKana]

一般人只觉得自己不爱写、没时间、不擅长、没必要等等，但深层原因其实主要有两点：

1. 得不到不重视。2. 不算钱不算业绩。

如果写一手好文档能算业绩、受表扬、加奖金、纳入升职 kpi，得到重视，受到业界认可有利于跳槽，那么很多人就会自然爱写文档。

现实是花时间写文档带来的好处太少，有那个时间，做点别的收益更大，就这么简单。

[apifox]

# 为什么开发人员不愿写接口文档？是你没用对方法

> 大多数开发人员不愿意写接口文档的原因是：`写文档短期收益远低于付出的成本`，然而并不是所有人都能够坚持做有`长期收益`的事情的。你因为写文档而耽误了当前项目进度，老板会直接找你麻烦；但是因为没写文档而带来的长期收益低，老板是看不见的。这就是现实，让人去做违反人性的事情是非常困难的。

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

那能不能写好接口文档，大家都按文档来开发？很难，程序员最讨厌的两件事：1. 写文档，2. 别人不写文档。因为写文档、维护文档比较麻烦，而且费时，还会经常出现 API 更新了，但文档还是旧的，各种同步不一致的情况，从而耽搁彼此的时间。

之前我们团队也遇到了同样的问题，那么作为研发团队的负责人，我是如何带领团队解决这个问题的呢？

## 如何做？

方法其实很简单，如果能做到让写文档 /维护文档这件事情的`短期收益`就能远高于`付出的成本`，那么所有问题都能迎刃而解，开发人员就会非常乐意去写接口文档。

#### 团队原来的工作模式

1. 使用 Swagger 写接口文档
2. **前端开发** 使用 RAP mock 接口数据
3. **后端开发** 使用 Postman 调试接口
4. **测试人员** 使用 JMeter 测试接口

#### 我们遇到的问题

1. 我们团队是前后端同步进入开发的，不能等后端开发完了才出接口文档，前端再进入开发，所以使用后端代码注释自动生成 Swagger 不适合我们。
2. 写 Swagger 文档效率很低，并且有学习门槛，让团队所有人都熟练手写 Swagger 文档是不现实的，更何况团队不停有新人进来。
3. 开发人员在 Swagger 定义好文档后，接口调试的时候还需要去 Postman 再定义一遍。
4. 前端开发 Mock 数据的时候又要去 RAP 定义一遍，手动设置好 Mock 规则。
5. 测试人员需要去 JMeter 定义一遍。
6. 前端根据 RAP Mock 出来的数据开发完，后端根据 Swagger 定义的接口文档开发完，各自测试测试通过了，本以为可以马上上线，结果一对接发现各种问题：原来开发过程中接口变更，只修改了 Swagger，但是没有及时同步修改 RAP 。
7. 同样，测试在 JMeter 写好的测试用例，真正运行的时候也会发现各种不一致。
8. 开发过程，经常会有发现开始定义的接口文档有不合理的地方，需要临时调整，经常出现接口改了，但是文档没有更新。
9. 时间久了，各种不一致会越来越严重。

### 如何解决

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

1. 降低写文档的成本
2. 增加写文档后的收益

鉴于此，我们设想如果有一款工具做到以下这些是不是就非常爽了？

1. 以`完全可视化`的界面来编写文档，并且是零学习成本，**新人** 一来就能上手。
2. 可以通过接口文档定义的数据结构`自动 mock`出数据，而无需 **前端开发** 再写`mock`规则。
3. **后端开发** 在接口文档基础上调试接口，而无需在去`Postman`上调试；接口如有变化，调试的时候就自动更新了文档，零成本的保障了接口维护的及时性。
4. **后端开发** 每次调试完一个功能就保存为一个`接口用例`。
5. **测试人员** 直接使用`接口用例`测试接口。
6. **测试人员** 更加接口文档自动生成测试用例，然后像`JMeter`一样在直接在上面测试。
7. 根据接口文档定义的数据结构，自动生成前后端的`数据模型`代码。

总结下来，我们需要的就是这么一款工具：

> 通过一套系统、一份数据，解决多个系统之间的数据同步问题。只要定义好接口文档，接口调试、数据 Mock 、接口测试就可以直接使用，无需再次定义；接口文档和接口开发调试使用同一个工具，接口调试完成后即可保证和接口文档定义完全一致。高效、及时、准确！

为此，我们几乎尝遍了市面上所有相关的工具，但是很遗憾，没有找到合适的。

#### 怎么办？自己干！

于是，我们自己实现了一个`Postman + Swagger + RAP + JMeter`

这个工具就是 `Apifox`，经常很长一段时间不断更新迭代后，我们基本上完全实现了最初的设想，几乎完美解决了最开始遇到的所有问题，在公司内部大受欢迎。并且也形成了我们自己的最佳实践。

## 最佳实践

1. **前端**（或**后端**）在 **Apifox** 上定好`接口文档`初稿。
2. **前后端** 一起评审、完善`接口文档`，定好`接口用例`。
3. **前端** 使用系统根据接口文档自动生成的 `Mock 数据`进入开发。
4. **后端** 使用`接口用例` 调试开发中接口，系统根据接口文档的定义`自动校验`返回的数据是否正确，只要所有接口用例调试通过，接口就开发完成了。
5. **后端** 开发完成后，**测试人员**（也可以是**后端**）使用`集合测试`功能进行多接口集成测试，完整测试整个接口调用流程。
6. **前后端** 都开发完，前端从`Mock 数据`切换到`正式数据`，联调通常都会非常顺利，因为前后端双方都完全遵守了接口定义的规范。

## 对外服务

没错，现在我们已经将`Apifox`产品化对外服务了，你们团队也可以直接使用`Apifox`了。

官网：[www.apifox.cn]( https://www.apifox.cn/)

## Apifox 主要功能

1. **接口设计**：Apifox 接口文档遵循 [OpenApi]( https://www.openapis.org/) 3.0 (原 Swagger)、[JSON Schema]( https://json-schema.org/) 规范的同时，提供了非常好用的`可视化`文档管理功能，零学习成本，非常高效。
2. **数据模型**：可复用的数据结构，定义接口`返回数据结构`及`请求参数数据结构`（仅 JSON 和 XML 模式）时可直接引用。
3. **接口调试**：Postman 有的功能，比如环境变量、前置 /后置脚本、Cookie/Session 全局共享 等功能，Apifox 都有，并且和 Postman 一样高效好用。接口运行完之后点击`保存为用例`按钮，即可生成`接口用例`，后续可直接运行接口用例，无需再输入参数，非常方便。
4. **接口用例**：通常一个接口会有多种情况用例，比如`参数正确`用例、`参数错误`用例、`数据为空`用例、`不同数据状态`用例等等。运行接口用例时会自动校验数据正确性，用接口用例来调试接口非常高效。
5. **数据 Mock**：内置 [Mock.js]( http://mockjs.com/) 规则引擎，非常方便 mock 出各种数据，并且可以在定义数据结构的同时写好 mock 规则。支持添加“期望”，根据请求参数返回不同 mock 数据。最重要的是 Apifox `零配置` 即可 Mock 出非常人性化的数据，具体在本文后面介绍。
6. **接口自动化测试**：提供接口集合测试，可以通过选择接口（或接口用例）快速创建测试集。目前接口自动化测试更多功能还在开发中，敬请期待！目标是：JMeter 有的功能基本都会有，并且要更好用。
7. **快捷调试**：类似 Postman 的接口调试方式，主要用途为临时调试一些`无需文档化`的接口，无需提前定义接口即可快速调试。
8. **代码生成**：根据接口及数据数据模型定义，系统自动生成`接口请求代码`、`前端业务代码`及`后端业务代码`。
9. **团队协作**：Apifox 天生就是为团队协作而生的，接口云端实时同步更新，成熟的`团队 /项目 /成员权限`管理，满足各类企业的需求。

## Apifox 截图

[接口文档工具]( https://www.apifox.cn/)
官网：[www.apifox.cn]( https://www.apifox.cn/)

[coderluan]

大部分开发人员为不愿意写任何文档, 对接口文档只是一视同仁而已.

[NCE]

1. 写文档的复杂度等同于写代码；

2.写文档的价值体现远远低于写代码。

[MuscleOf2016]

1 、自己会认证写文档
2 、审别人代码，会一同审核文档，不满意不会给通过

[akira]

老板没给时间

[a719031256]

我个人觉得最关键的还是需求变更很频繁

有时候按早期需求设计好接口，文档写好了，结果早期需求还没完全做好，需求就又变了

我遇到不管是小项目还是大项目，都这样

[66450146]

把接口调得能通过机器检查容易

想清楚系统的结构和逻辑并清晰地表达出来很难

写文档就是后者

[JerryCha]

应付需求已经很累了，还写文档那是连午睡都搭进去了

[knightdf]

可能上级定任务时间的时候压根就没考虑你写文档的时间

[tianxia]

因为自己觉得还有变动

[echo1937]

老板没给这个时间

[foxtalk]

大公司应该好一点，小公司的领导们，大多不注重代码规范，接口设计，只是抱着能用就行的思维，没有留出足够的时间让你好好设计接口和文档，在他们眼里，项目的进度重要程度是远远大于代码质量和设计文档的。大公司里面有代码审核人员，会好很多。

[Euthpic]

@apifox 考虑下 yapi

[kingfalse]

因为写文档不算工作量

[sytnishizuiai]

前后分离，不写文档，前端怎么开发啊？哪知道传什么，返回什么。

不过文档确实累心，开发的时候忙的要死，还要写文档，开发完了又是一堆事，我是没办法，前后端都在家办公，全靠文档开发。

还有一部分原因在于领导，很多人认为代码跑起来就项目结束，再搞一个。剩下的代码优化，文档写完整，sql 优化也懒的搞了，没精力。

[so1n]

写文档很累。。。所以我就自己写了一个框架来自动生成文档 https://github.com/so1n/pait

[icy37785]

自己的项目最烦写文档，别人的项目最烦没文档。
可能这就是社会主义初级阶段的主要矛盾把。

[wolong]

因为不会写

[skys215]

因为程序员只会写代码，不会写人话。

[Kontinue]

新项目和前端对接或者需要第三方对接的时候会写。但是后面需求改动的时候就懒得再改文档了。。。

[ada87]

标题说了，主要就是因为不愿意。

早上 9 点上班，激情满满的码代码，可以一口激情码到下班。
要是写一小时接口文档，写到 10 点，一整天的心情都不好了，特别是本来就还有干不完的活的情况下（借口），码代码的心情也没了，写代码心情差，效率质量齐下降。

[Kontinue]

其实都是相对的，和别人对接，不写文档，自然很多细节的地方别人都会来问你，还不如一次性都写清楚

[jorneyr]

自己不写有合理的理由，但常常抱怨别人不写。

[From313]

YAPI + 1

[niub]

写。

[andytao]

因为代码即文档，代码是最新最完整的文档呀。

[Felldeadbird]

任务堆积，文档重视程度低。 决策层决定开发质量。

[cedoo22]

@AoEiuV020 如果新来一个前端程序员， 也要用原来的接口，但是参数值会有点调整，这时候是直接看代码嘛？？？

[cedoo22]

@NCE 我反而觉得文档有时候和代码一样重要，如果是对外的接口更不用说

[AoEiuV020]

@cedoo22 一般来说是的，写代码的员工还在的话可能会问一下，不在就只能检查代码了，运气好可能有点注释，

[AoEiuV020]

@cedoo22 重要归重要，但那是对别人重要，不是对自己，又没有这方面业绩指标要求，舍己为人还是有点难的，

[aicfe]

公司用 yApi，所以用 idea 搭配 easyYapi 更香，一键导出到 yapi

[mosliu]

yapi 很好用。

[apifox]

曾经用过 YApi，连数据结构都没法复用，放弃了

[biaomingzhong]

我们之前用 YApi，现在改用 Apifox， 基本不存在这个问题了

[loryyang]

多一事不如少一事，另外，代码变化文档也要跟着变，成本确实太高了
我觉得妥协方案，还是尽量把代码写简单自解释，不要过度设计

[wangyzj]

把接口二字去掉吧
任何文档都不想写

[p1gd0g]

都内卷成这样了，老板会在意你写不写文档？

[yuankui]

我每天要对机器说那么多话（码代码）都那么累了，那还有时间和精力对人说话（写文档）？

[SwimmingDragon]

前端说，我写的文档还没有我的代码容易看懂。所以我就没有写文档了

[intmax2147483647]

应该整一个专门写接口文档的岗位

[nekoneko]

postman 测试完一键生成文档就行了

[polyang]

开发人员最讨厌的事：
1 、别人不写接口文档；
2 、让我写接口文档。

[neptuno]

写了很多人也不看呀，，，还是跑过来跟我说你这字段啥意思呀

[Bigglesworth]

postman 也可以发布文档

[yolee599]

因为写文档不计入工时

[dfkjgklfdjg]

写代码的同时搭配注解就可以完成一些额外工作，不想写的其实都是懒得写，而且麻烦，用注释可以完成不就好了，
我自己也尝试过，用 JS 实现了一部分的自动生成文档，后来后端用了 Swagger 我这边就不需要做文档了。

Swagger 通过注解的方式来生成对应的 API，包括自动文档，代码生成和测试用例生成。

[romisanic]

一方面是懒吧，就是不想多花力气
另一方面是对于一些人而言，深入思考规划的能力比较欠缺，导致不用等到新的需求，本次需求实现过程中就要多次修改接口方案，原本只需要改一下代码，现在还需要同步设计文档，会觉得麻烦很多
还有一个常见的情况是任务没有给写文档的时间

[lazy21]

apifox +1

[xcstream]

看情况 慢工细活 弄弄文档很合理。
追求速度，能用就行。

[qdzzyb]

不给时间 写什么文档

[wanguorui123]

不都是自动生成的吗？

[jessezhang1986]

@apifox 牛逼，这个 Apifox （ apifox.cn ） 确实可以解决这个问题

[LemonK]

捏着鼻子逼自己仔仔细细写好文档，然而前端根本不看，还是动不动来问。
没文档，问了你直接回答就行。有文档，你为了证明有文档，还得打开 VPN，打开文档页，找到对应接口，截图那一两行给他。
这种情况发生个一二十次，成功培养了我不写文档的好习惯。

[charlie21]

有专人负责写文档

[AlanDSF]

@AoEiuV020 逻辑毫无毛病，同感

[luvroot]

对自己意义不大

[gy0624ww]

都是国内 IT 畸形发展的结果
包括单元测试

[old9]

这一唱一和广告打的

[gucheen]

这么多人还没看出来这就是个推广贴

[falcon05]

@gucheen
@old9

真相了，看了下这楼主的历史回复，这…

[juwins1993]

我们这边用 yapi 管理接口，然后用 idea 插件生成文档并推送，不需要专门写

[normanzhxu]

@juwins1993 我这里也有 yapi 。同时在代码框架上也支持检测接口 并获取接口信息的

[codepark]

虽然是广告 我就不妨试试 apifox 哈哈

[chenshun00]

其实还是一个投入产出比的问题，写文档对当时的人来说投入过多了，但是又没有什么收益。毕竟接口开发完了(kpi?) ， 能用就行了.

为了降低投入，搞了一个 IDEA 插件，一键手机，投入从 1 降低到 0.05 。

[aboutyang]

国内开发项目大都是打兴奋剂模式，缺的不止是接口文档。

[ghos]

@chenshun00 插件主要做哪些功能

[vinceall]

程序员最反感两件事：自己写文档，别人不写文档

[chenyu0532]

因为不算 kpi 吧。。

[www5070504]

接口文档还好说 项目文档 设计文档才是真恶心

[Huelse]

写文档的时间已经花在下一个需求上了

[tomari]

因为可以自动生成（

[tonghuashuai]

我想写，我真的想写，发自内心的想写

[Gunn27]

因为程序员觉得写文档太麻烦了，如果写文档的成本没那么高，那么就不会有抗拒心理。试试 https://apicat.net

[ss77]

哇，最近刚切换到 apifox，拿来测试太优秀了

[MeteorCat]

赶工期

[liuxu]

我现在和朋友做项目都是先出 openapi3 的文档，写一份下来很累，准备以后就 postman 搞一搞了，测试，mock 一起出

[py2ex]

@apifox 看回答看到一半就警惕了，看剩下的部分，果然！返回去按回复才发现 ID 早已预告🤣
不过这个回复算是比较诚恳的推广

[Armour]

给算进排期的话还是很愿意写的

[ptrees]

我觉得真的好用好好宣传就行了,这么套路给人很心机的感觉,反而让人警惕😅

[hewiefsociety]

因为懒

[kkzxak47]

因为他们连接口都不想写。
再就是不专业，其实 90%的写代码的人都不专业。