这是一个创建于 1219 天前的主题，其中的信息可能已经有所发展或是发生改变。
 |
1
falcon05 2021-07-21 18:38:39 +08:00 via iPhone  30
你愿意写吗？
|
 |
2
balabalaguguji 2021-07-21 18:40:06 +08:00
因为太麻烦了，不过可以借助一些比较方便的工具来写 https://easydoc.net
|
 |
3
securityCoding 2021-07-21 18:44:43 +08:00 1
基本都在用 swagger 标准化了，不存在写不写的问题
|
 |
4
AoEiuV020 2021-07-21 18:53:29 +08:00 via Android 45
开发的时候很多不确定，写了可能要改，
开发完了，都已经能用了还写什么文档，而且下个任务来了，也没时间， |
 |
6
Building 2021-07-21 18:58:50 +08:00 via iPhone 1
现在编程语言关键字一个比一个多，命名一个比一个长，你觉得是为了什么？显得高级吗？
|
 |
7
CEBBCAT 2021-07-21 18:59:37 +08:00 via Android 1
我最讨厌写文档以及别人不写文档！
我写一个接口文档可能就要写半天，要先写 demo，再写行为，再写异常 case 下的行为，还要调得漂漂亮亮的，唉，做人难，做开发，更难 |
 |
8
yuandj 2021-07-21 18:59:52 +08:00
推荐 ApiPost 接口联调工具，可以多人协作，自己进行接口测试时，就可以生成文档发布
|
 |
9
silencil 2021-07-21 19:02:59 +08:00 via iPhone 2
文档是对我代码可读性的侮辱(手动狗头🐶)
|
 |
10
IvanLi127 2021-07-21 19:04:10 +08:00 via Android
愿意写接口文档的路过。。。
|
|
11
silencil 2021-07-21 19:06:18 +08:00 via iPhone 1
正经回答其实上面已经说了，如 Java，关键的代码抽成方法，命名体现功能，各方面规范些再加上 Java 代码的可读性，整体来说我觉的已经足够替代文档了。真正需要的文档应该是需求文档，设计文档。
|
 |
12
dqzcwxb 2021-07-21 19:11:44 +08:00 32
我哪是不想写文档,我压根就不想工作
|
 |
13
bojackhorseman 2021-07-21 19:15:19 +08:00 via iPhone
@dqzcwxb 真相了
|
 |
14
cmdOptionKana 2021-07-21 19:27:01 +08:00 2
一般人只觉得自己不爱写、没时间、不擅长、没必要等等，但深层原因其实主要有两点：
1. 得不到不重视。2. 不算钱不算业绩。 如果写一手好文档能算业绩、受表扬、加奖金、纳入升职 kpi，得到重视，受到业界认可有利于跳槽，那么很多人就会自然爱写文档。 现实是花时间写文档带来的好处太少，有那个时间，做点别的收益更大，就这么简单。 |
 |
15
apifox 2021-07-21 19:28:30 +08:00 8
# 为什么开发人员不愿写接口文档？是你没用对方法
> 大多数开发人员不愿意写接口文档的原因是：`写文档短期收益远低于付出的成本`，然而并不是所有人都能够坚持做有`长期收益`的事情的。你因为写文档而耽误了当前项目进度，老板会直接找你麻烦；但是因为没写文档而带来的长期收益低，老板是看不见的。这就是现实，让人去做违反人性的事情是非常困难的。 作为一个前后端分离模式开发的团队，我们经常会看到这样的场景：前端开发和后端开发在一起热烈的讨论“你这接口参数怎么又变了？”，“接口怎么又不通了？”，“稍等，我调试下”，“你再试试..."。 那能不能写好接口文档，大家都按文档来开发？很难，程序员最讨厌的两件事：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/) |
 |
16
coderluan 2021-07-21 19:36:49 +08:00 1
大部分开发人员为不愿意写任何文档, 对接口文档只是一视同仁而已.
|
 |
17
NCE 2021-07-21 20:20:53 +08:00
1. 写文档的复杂度等同于写代码；
2.写文档的价值体现远远低于写代码。 |
 |
18
MuscleOf2016 2021-07-21 20:30:36 +08:00
1 、自己会认证写文档
2 、审别人代码，会一同审核文档，不满意不会给通过 |
 |
19
akira 2021-07-21 21:23:40 +08:00
老板没给时间
|
 |
20
a719031256 2021-07-21 21:34:28 +08:00
我个人觉得最关键的还是需求变更很频繁
有时候按早期需求设计好接口，文档写好了，结果早期需求还没完全做好，需求就又变了 我遇到不管是小项目还是大项目，都这样 |
 |
21
66450146 2021-07-21 21:42:59 +08:00
把接口调得能通过机器检查容易
想清楚系统的结构和逻辑并清晰地表达出来很难 写文档就是后者 |
 |
22
JerryCha 2021-07-21 22:04:31 +08:00
应付需求已经很累了，还写文档那是连午睡都搭进去了
|
 |
23
knightdf 2021-07-21 22:08:58 +08:00
可能上级定任务时间的时候压根就没考虑你写文档的时间
|
 |
24
tianxia 2021-07-21 22:27:04 +08:00 via Android
因为自己觉得还有变动
|
 |
25
echo1937 2021-07-21 23:30:51 +08:00 via iPhone
老板没给这个时间
|
 |
26
foxtalk 2021-07-21 23:50:46 +08:00
大公司应该好一点，小公司的领导们，大多不注重代码规范，接口设计，只是抱着能用就行的思维，没有留出足够的时间让你好好设计接口和文档，在他们眼里，项目的进度重要程度是远远大于代码质量和设计文档的。大公司里面有代码审核人员，会好很多。
|
 |
28
kingfalse 2021-07-22 00:21:48 +08:00 via Android
因为写文档不算工作量
|
 |
29
sytnishizuiai 2021-07-22 00:45:59 +08:00
前后分离，不写文档，前端怎么开发啊？哪知道传什么，返回什么。
不过文档确实累心，开发的时候忙的要死，还要写文档，开发完了又是一堆事，我是没办法，前后端都在家办公，全靠文档开发。 还有一部分原因在于领导，很多人认为代码跑起来就项目结束，再搞一个。剩下的代码优化，文档写完整，sql 优化也懒的搞了，没精力。 |
 |
30
so1n 2021-07-22 00:56:00 +08:00
写文档很累。。。所以我就自己写了一个框架来自动生成文档 https://github.com/so1n/pait
|
 |
31
icy37785 2021-07-22 03:06:35 +08:00 2
自己的项目最烦写文档，别人的项目最烦没文档。
可能这就是社会主义初级阶段的主要矛盾把。 |
 |
32
wolong 2021-07-22 06:51:03 +08:00
因为不会写
|
 |
33
skys215 2021-07-22 08:36:33 +08:00
因为程序员只会写代码，不会写人话。
|
 |
34
Kontinue 2021-07-22 08:46:31 +08:00
新项目和前端对接或者需要第三方对接的时候会写。但是后面需求改动的时候就懒得再改文档了。。。
|
 |
35
ada87 2021-07-22 08:46:37 +08:00
标题说了，主要就是因为不愿意。
早上 9 点上班，激情满满的码代码，可以一口激情码到下班。 要是写一小时接口文档，写到 10 点，一整天的心情都不好了，特别是本来就还有干不完的活的情况下（借口），码代码的心情也没了，写代码心情差，效率质量齐下降。 |
|
36
Kontinue 2021-07-22 08:47:41 +08:00
其实都是相对的，和别人对接，不写文档，自然很多细节的地方别人都会来问你，还不如一次性都写清楚
|
 |
37
jorneyr 2021-07-22 08:57:09 +08:00
自己不写有合理的理由，但常常抱怨别人不写。
|
 |
38
From313 2021-07-22 08:58:24 +08:00
YAPI + 1
|
 |
39
niub 2021-07-22 09:07:58 +08:00
写。
|
 |
40
andytao 2021-07-22 09:17:14 +08:00
因为代码即文档，代码是最新最完整的文档呀。
|
 |
41
Felldeadbird 2021-07-22 09:22:12 +08:00
任务堆积，文档重视程度低。 决策层决定开发质量。
|
 |
46
aicfe 2021-07-22 09:32:29 +08:00
公司用 yApi，所以用 idea 搭配 easyYapi 更香，一键导出到 yapi
|
 |
47
mosliu 2021-07-22 09:38:26 +08:00
yapi 很好用。
|
|
48
apifox 2021-07-22 09:42:14 +08:00
曾经用过 YApi，连数据结构都没法复用，放弃了
|
 |
49
biaomingzhong 2021-07-22 09:50:13 +08:00 1
我们之前用 YApi，现在改用 Apifox， 基本不存在这个问题了
|
 |
50
loryyang 2021-07-22 09:57:57 +08:00
多一事不如少一事，另外，代码变化文档也要跟着变，成本确实太高了
我觉得妥协方案，还是尽量把代码写简单自解释，不要过度设计 |
 |
51
wangyzj 2021-07-22 10:10:37 +08:00
把接口二字去掉吧
任何文档都不想写 |
 |
52
p1gd0g 2021-07-22 10:14:43 +08:00
都内卷成这样了，老板会在意你写不写文档？
|
 |
53
yuankui 2021-07-22 10:18:58 +08:00
我每天要对机器说那么多话（码代码）都那么累了，那还有时间和精力对人说话（写文档）？
|
 |
54
SwimmingDragon 2021-07-22 10:22:52 +08:00
前端说，我写的文档还没有我的代码容易看懂。所以我就没有写文档了
|
 |
55
intmax2147483647 2021-07-22 10:52:16 +08:00
应该整一个专门写接口文档的岗位
|
 |
56
nekoneko 2021-07-22 10:53:45 +08:00
postman 测试完一键生成文档就行了
|
 |
57
polyang 2021-07-22 10:57:13 +08:00
开发人员最讨厌的事：
1 、别人不写接口文档； 2 、让我写接口文档。 |
 |
58
neptuno 2021-07-22 11:01:43 +08:00
写了很多人也不看呀，，，还是跑过来跟我说你这字段啥意思呀
|
 |
59
Bigglesworth 2021-07-22 11:06:24 +08:00
postman 也可以发布文档
|
 |
60
yolee599 2021-07-22 11:08:46 +08:00
因为写文档不计入工时
|
 |
61
dfkjgklfdjg 2021-07-22 11:12:40 +08:00
写代码的同时搭配注解就可以完成一些额外工作，不想写的其实都是懒得写，而且麻烦，用注释可以完成不就好了，
我自己也尝试过，用 JS 实现了一部分的自动生成文档，后来后端用了 Swagger 我这边就不需要做文档了。 Swagger 通过注解的方式来生成对应的 API，包括自动文档，代码生成和测试用例生成。 |
 |
62
romisanic 2021-07-22 11:25:36 +08:00
一方面是懒吧，就是不想多花力气
另一方面是对于一些人而言，深入思考规划的能力比较欠缺，导致不用等到新的需求，本次需求实现过程中就要多次修改接口方案，原本只需要改一下代码，现在还需要同步设计文档，会觉得麻烦很多 还有一个常见的情况是任务没有给写文档的时间 |
 |
63
lazy21 2021-07-22 11:34:44 +08:00 1
apifox +1
|
 |
64
xcstream 2021-07-22 11:57:15 +08:00
看情况 慢工细活 弄弄文档很合理。
追求速度，能用就行。 |
 |
65
qdzzyb 2021-07-22 11:57:29 +08:00
不给时间 写什么文档
|
 |
66
wanguorui123 2021-07-22 12:24:52 +08:00
不都是自动生成的吗？
|
 |
67
jessezhang1986 OP |
 |
68
LemonK 2021-07-22 13:19:42 +08:00
捏着鼻子逼自己仔仔细细写好文档，然而前端根本不看，还是动不动来问。
没文档，问了你直接回答就行。有文档，你为了证明有文档，还得打开 VPN，打开文档页，找到对应接口，截图那一两行给他。 这种情况发生个一二十次，成功培养了我不写文档的好习惯。 |
 |
69
charlie21 2021-07-22 13:51:42 +08:00
有专人负责写文档
|
 |
71
luvroot 2021-07-22 14:20:11 +08:00
对自己意义不大
|
 |
73
gy0624ww 2021-07-22 14:45:19 +08:00
都是国内 IT 畸形发展的结果
包括单元测试 |
 |
74
old9 2021-07-22 14:46:26 +08:00
这一唱一和广告打的
|
 |
75
gucheen 2021-07-22 14:47:09 +08:00 1
这么多人还没看出来这就是个推广贴
|
 |
77
juwins1993 2021-07-22 14:58:16 +08:00
我们这边用 yapi 管理接口，然后用 idea 插件生成文档并推送，不需要专门写
|
 |
78
normanzhxu 2021-07-22 15:17:31 +08:00
@juwins1993 我这里也有 yapi 。同时在代码框架上也支持检测接口 并获取接口信息的
|
 |
79
codepark 2021-07-22 15:20:04 +08:00
虽然是广告 我就不妨试试 apifox 哈哈
|
 |
80
chenshun00 2021-07-22 15:28:33 +08:00
其实还是一个投入产出比的问题，写文档对当时的人来说投入过多了，但是又没有什么收益。毕竟接口开发完了(kpi?) ， 能用就行了.
为了降低投入，搞了一个 IDEA 插件，一键手机，投入从 1 降低到 0.05 。 |
 |
81
aboutyang 2021-07-22 15:37:31 +08:00
国内开发项目大都是打兴奋剂模式，缺的不止是接口文档。
|
 |
82
ghos 2021-07-22 15:39:48 +08:00
@chenshun00 插件主要做哪些功能
|
 |
83
vinceall 2021-07-22 16:04:37 +08:00
程序员最反感两件事：自己写文档，别人不写文档
|
 |
84
chenyu0532 2021-07-22 16:09:27 +08:00
因为不算 kpi 吧。。
|
 |
85
www5070504 2021-07-22 16:39:29 +08:00
接口文档还好说 项目文档 设计文档才是真恶心
|
 |
86
Huelse 2021-07-22 17:02:54 +08:00
写文档的时间已经花在下一个需求上了
|
 |
87
tomari 2021-07-22 17:11:39 +08:00
因为可以自动生成（
|
 |
88
tonghuashuai 2021-07-22 17:49:06 +08:00
我想写，我真的想写，发自内心的想写
|
 |
89
Gunn27 2021-07-22 18:09:43 +08:00
因为程序员觉得写文档太麻烦了，如果写文档的成本没那么高，那么就不会有抗拒心理。试试 https://apicat.net
|
 |
90
ss77 2021-07-22 18:59:18 +08:00
哇，最近刚切换到 apifox，拿来测试太优秀了
|
 |
91
MeteorCat 2021-07-22 19:02:39 +08:00 via Android
赶工期
|
 |
92
liuxu 2021-07-22 19:29:43 +08:00
我现在和朋友做项目都是先出 openapi3 的文档，写一份下来很累，准备以后就 postman 搞一搞了，测试，mock 一起出
|
 |
94
Armour 2021-07-23 10:41:59 +08:00
给算进排期的话还是很愿意写的
|
 |
95
ptrees 2021-07-23 14:36:49 +08:00
我觉得真的好用好好宣传就行了,这么套路给人很心机的感觉,反而让人警惕😅
|
 |
96
hewiefsociety 2021-07-23 16:12:00 +08:00
因为懒
|
 |
97
kkzxak47 2021-07-24 11:38:16 +08:00 via Android
因为他们连接口都不想写。
再就是不专业，其实 90%的写代码的人都不专业。 |
Select Language