V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
jessezhang1986
V2EX  ›  程序员

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

  •  
  •   jessezhang1986 · 13 天前 · 7828 次点击
    97 条回复    2021-07-24 11:38:16 +08:00
    falcon05
        1
    falcon05   13 天前 via iPhone   ❤️ 30
    你愿意写吗?
    balabalaguguji
        2
    balabalaguguji   13 天前
    因为太麻烦了,不过可以借助一些比较方便的工具来写 https://easydoc.net
    securityCoding
        3
    securityCoding   13 天前   ❤️ 1
    基本都在用 swagger 标准化了,不存在写不写的问题
    AoEiuV020
        4
    AoEiuV020   13 天前 via Android   ❤️ 45
    开发的时候很多不确定,写了可能要改,
    开发完了,都已经能用了还写什么文档,而且下个任务来了,也没时间,
    aaniao002
        5
    aaniao002   13 天前 via Android   ❤️ 1
    @AoEiuV020 up,深入灵魂的回答。
    Building
        6
    Building   13 天前 via iPhone   ❤️ 1
    现在编程语言关键字一个比一个多,命名一个比一个长,你觉得是为了什么?显得高级吗?
    CEBBCAT
        7
    CEBBCAT   13 天前 via Android   ❤️ 1
    我最讨厌写文档以及别人不写文档!

    我写一个接口文档可能就要写半天,要先写 demo,再写行为,再写异常 case 下的行为,还要调得漂漂亮亮的,唉,做人难,做开发,更难
    yuandj
        8
    yuandj   13 天前
    推荐 ApiPost 接口联调工具,可以多人协作,自己进行接口测试时,就可以生成文档发布
    silencil
        9
    silencil   13 天前 via iPhone   ❤️ 2
    文档是对我代码可读性的侮辱(手动狗头🐶)
    IvanLi127
        10
    IvanLi127   13 天前 via Android
    愿意写接口文档的路过。。。
    silencil
        11
    silencil   13 天前 via iPhone   ❤️ 1
    正经回答其实上面已经说了,如 Java,关键的代码抽成方法,命名体现功能,各方面规范些再加上 Java 代码的可读性,整体来说我觉的已经足够替代文档了。真正需要的文档应该是需求文档,设计文档。
    dqzcwxb
        12
    dqzcwxb   13 天前   ❤️ 32
    我哪是不想写文档,我压根就不想工作
    bojackhorseman
        13
    bojackhorseman   13 天前 via iPhone
    @dqzcwxb 真相了
    cmdOptionKana
        14
    cmdOptionKana   13 天前   ❤️ 2
    一般人只觉得自己不爱写、没时间、不擅长、没必要等等,但深层原因其实主要有两点:

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

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

    现实是花时间写文档带来的好处太少,有那个时间,做点别的收益更大,就这么简单。
    apifox
        15
    apifox   13 天前   ❤️ 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 截图
    ![Apifox 接口文档工具]( https://cdn3.apifox.cn/www/screenshot/apifox-api-case-1.png)

    [接口文档工具]( https://www.apifox.cn/)
    官网:[www.apifox.cn]( https://www.apifox.cn/)
    coderluan
        16
    coderluan   13 天前   ❤️ 1
    大部分开发人员为不愿意写任何文档, 对接口文档只是一视同仁而已.
    NCE
        17
    NCE   13 天前
    1. 写文档的复杂度等同于写代码;

    2.写文档的价值体现远远低于写代码。
    MuscleOf2016
        18
    MuscleOf2016   13 天前
    1 、自己会认证写文档
    2 、审别人代码,会一同审核文档,不满意不会给通过
    akira
        19
    akira   13 天前
    老板没给时间
    a719031256
        20
    a719031256   13 天前
    我个人觉得最关键的还是需求变更很频繁

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

    我遇到不管是小项目还是大项目,都这样
    66450146
        21
    66450146   13 天前
    把接口调得能通过机器检查容易

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

    写文档就是后者
    JerryCha
        22
    JerryCha   13 天前
    应付需求已经很累了,还写文档那是连午睡都搭进去了
    knightdf
        23
    knightdf   13 天前
    可能上级定任务时间的时候压根就没考虑你写文档的时间
    tianxia
        24
    tianxia   13 天前 via Android
    因为自己觉得还有变动
    echo1937
        25
    echo1937   13 天前 via iPhone
    老板没给这个时间
    foxtalk
        26
    foxtalk   13 天前
    大公司应该好一点,小公司的领导们,大多不注重代码规范,接口设计,只是抱着能用就行的思维,没有留出足够的时间让你好好设计接口和文档,在他们眼里,项目的进度重要程度是远远大于代码质量和设计文档的。大公司里面有代码审核人员,会好很多。
    Euthpic
        27
    Euthpic   13 天前
    @apifox 考虑下 yapi
    kingfalse
        28
    kingfalse   13 天前 via Android
    因为写文档不算工作量
    sytnishizuiai
        29
    sytnishizuiai   13 天前
    前后分离,不写文档,前端怎么开发啊?哪知道传什么,返回什么。

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

    还有一部分原因在于领导,很多人认为代码跑起来就项目结束,再搞一个。剩下的代码优化,文档写完整,sql 优化也懒的搞了,没精力。
    so1n
        30
    so1n   13 天前
    写文档很累。。。所以我就自己写了一个框架来自动生成文档 https://github.com/so1n/pait
    icy37785
        31
    icy37785   13 天前   ❤️ 2
    自己的项目最烦写文档,别人的项目最烦没文档。
    可能这就是社会主义初级阶段的主要矛盾把。
    wolong
        32
    wolong   13 天前
    因为不会写
    skys215
        33
    skys215   13 天前
    因为程序员只会写代码,不会写人话。
    Kontinue
        34
    Kontinue   13 天前
    新项目和前端对接或者需要第三方对接的时候会写。但是后面需求改动的时候就懒得再改文档了。。。
    ada87
        35
    ada87   13 天前
    标题说了,主要就是因为不愿意。

    早上 9 点上班,激情满满的码代码,可以一口激情码到下班。
    要是写一小时接口文档,写到 10 点,一整天的心情都不好了,特别是本来就还有干不完的活的情况下(借口),码代码的心情也没了,写代码心情差,效率质量齐下降。
    Kontinue
        36
    Kontinue   13 天前
    其实都是相对的,和别人对接,不写文档,自然很多细节的地方别人都会来问你,还不如一次性都写清楚
    jorneyr
        37
    jorneyr   13 天前
    自己不写有合理的理由,但常常抱怨别人不写。
    From313
        38
    From313   13 天前
    YAPI + 1
    niub
        39
    niub   13 天前
    写。
    andytao
        40
    andytao   13 天前
    因为代码即文档,代码是最新最完整的文档呀。
    Felldeadbird
        41
    Felldeadbird   13 天前
    任务堆积,文档重视程度低。 决策层决定开发质量。
    cedoo22
        42
    cedoo22   13 天前
    @AoEiuV020 如果新来一个前端程序员, 也要用原来的接口,但是参数值会有点调整,这时候是直接看代码嘛???
    cedoo22
        43
    cedoo22   13 天前   ❤️ 1
    @NCE 我反而觉得文档有时候和代码一样重要,如果是对外的接口更不用说
    AoEiuV020
        44
    AoEiuV020   13 天前
    @cedoo22 一般来说是的,写代码的员工还在的话可能会问一下,不在就只能检查代码了,运气好可能有点注释,
    AoEiuV020
        45
    AoEiuV020   13 天前
    @cedoo22 重要归重要,但那是对别人重要,不是对自己,又没有这方面业绩指标要求,舍己为人还是有点难的,
    aicfe
        46
    aicfe   13 天前
    公司用 yApi,所以用 idea 搭配 easyYapi 更香,一键导出到 yapi
    mosliu
        47
    mosliu   13 天前
    yapi 很好用。
    apifox
        48
    apifox   13 天前
    曾经用过 YApi,连数据结构都没法复用,放弃了
    biaomingzhong
        49
    biaomingzhong   13 天前   ❤️ 1
    我们之前用 YApi,现在改用 Apifox, 基本不存在这个问题了
    loryyang
        50
    loryyang   13 天前
    多一事不如少一事,另外,代码变化文档也要跟着变,成本确实太高了
    我觉得妥协方案,还是尽量把代码写简单自解释,不要过度设计
    wangyzj
        51
    wangyzj   13 天前
    把接口二字去掉吧
    任何文档都不想写
    p1gd0g
        52
    p1gd0g   13 天前
    都内卷成这样了,老板会在意你写不写文档?
    yuankui
        53
    yuankui   13 天前
    我每天要对机器说那么多话(码代码)都那么累了,那还有时间和精力对人说话(写文档)?
    SwimmingDragon
        54
    SwimmingDragon   13 天前
    前端说,我写的文档还没有我的代码容易看懂。所以我就没有写文档了
    intmax2147483647
        55
    intmax2147483647   13 天前
    应该整一个专门写接口文档的岗位
    nekoneko
        56
    nekoneko   13 天前
    postman 测试完一键生成文档就行了
    polyang
        57
    polyang   13 天前
    开发人员最讨厌的事:
    1 、别人不写接口文档;
    2 、让我写接口文档。
    neptuno
        58
    neptuno   13 天前
    写了很多人也不看呀,,,还是跑过来跟我说你这字段啥意思呀
    Bigglesworth
        59
    Bigglesworth   13 天前
    postman 也可以发布文档
    yolee599
        60
    yolee599   13 天前
    因为写文档不计入工时
    dfkjgklfdjg
        61
    dfkjgklfdjg   13 天前
    写代码的同时搭配注解就可以完成一些额外工作,不想写的其实都是懒得写,而且麻烦,用注释可以完成不就好了,
    我自己也尝试过,用 JS 实现了一部分的自动生成文档,后来后端用了 Swagger 我这边就不需要做文档了。

    Swagger 通过注解的方式来生成对应的 API,包括自动文档,代码生成和测试用例生成。
    romisanic
        62
    romisanic   13 天前
    一方面是懒吧,就是不想多花力气
    另一方面是对于一些人而言,深入思考规划的能力比较欠缺,导致不用等到新的需求,本次需求实现过程中就要多次修改接口方案,原本只需要改一下代码,现在还需要同步设计文档,会觉得麻烦很多
    还有一个常见的情况是任务没有给写文档的时间
    lazy21
        63
    lazy21   13 天前   ❤️ 1
    apifox +1
    xcstream
        64
    xcstream   13 天前
    看情况 慢工细活 弄弄文档很合理。
    追求速度,能用就行。
    qdzzyb
        65
    qdzzyb   13 天前
    不给时间 写什么文档
    wanguorui123
        66
    wanguorui123   13 天前
    不都是自动生成的吗?
    jessezhang1986
        67
    jessezhang1986   13 天前
    @apifox 牛逼,这个 Apifox ( apifox.cn ) 确实可以解决这个问题
    LemonK
        68
    LemonK   13 天前
    捏着鼻子逼自己仔仔细细写好文档,然而前端根本不看,还是动不动来问。
    没文档,问了你直接回答就行。有文档,你为了证明有文档,还得打开 VPN,打开文档页,找到对应接口,截图那一两行给他。
    这种情况发生个一二十次,成功培养了我不写文档的好习惯。
    charlie21
        69
    charlie21   13 天前
    有专人负责写文档
    AlanDSF
        70
    AlanDSF   13 天前
    @AoEiuV020 逻辑毫无毛病,同感
    luvroot
        71
    luvroot   13 天前
    对自己意义不大
    gy0624ww
        73
    gy0624ww   13 天前
    都是国内 IT 畸形发展的结果
    包括单元测试
    old9
        74
    old9   13 天前
    这一唱一和广告打的
    gucheen
        75
    gucheen   13 天前   ❤️ 1
    这么多人还没看出来这就是个推广贴
    falcon05
        76
    falcon05   13 天前 via iPhone
    @gucheen
    @old9

    真相了,看了下这楼主的历史回复,这…
    juwins1993
        77
    juwins1993   13 天前
    我们这边用 yapi 管理接口,然后用 idea 插件生成文档并推送,不需要专门写
    normanzhxu
        78
    normanzhxu   13 天前
    @juwins1993 我这里也有 yapi 。同时在代码框架上也支持检测接口 并获取接口信息的
    codepark
        79
    codepark   13 天前
    虽然是广告 我就不妨试试 apifox 哈哈
    chenshun00
        80
    chenshun00   13 天前
    其实还是一个投入产出比的问题,写文档对当时的人来说投入过多了,但是又没有什么收益。毕竟接口开发完了(kpi?) , 能用就行了.

    为了降低投入,搞了一个 IDEA 插件,一键手机,投入从 1 降低到 0.05 。
    aboutyang
        81
    aboutyang   13 天前
    国内开发项目大都是打兴奋剂模式,缺的不止是接口文档。
    ghos
        82
    ghos   13 天前
    @chenshun00 插件主要做哪些功能
    vinceall
        83
    vinceall   13 天前
    程序员最反感两件事:自己写文档,别人不写文档
    chenyu0532
        84
    chenyu0532   13 天前
    因为不算 kpi 吧。。
    www5070504
        85
    www5070504   13 天前
    接口文档还好说 项目文档 设计文档才是真恶心
    Huelse
        86
    Huelse   13 天前
    写文档的时间已经花在下一个需求上了
    tomari
        87
    tomari   13 天前
    因为可以自动生成(
    tonghuashuai
        88
    tonghuashuai   12 天前
    我想写,我真的想写,发自内心的想写
    Gunn27
        89
    Gunn27   12 天前
    因为程序员觉得写文档太麻烦了,如果写文档的成本没那么高,那么就不会有抗拒心理。试试 https://apicat.net
    ss77
        90
    ss77   12 天前
    哇,最近刚切换到 apifox,拿来测试太优秀了
    MeteorCat
        91
    MeteorCat   12 天前 via Android
    赶工期
    liuxu
        92
    liuxu   12 天前
    我现在和朋友做项目都是先出 openapi3 的文档,写一份下来很累,准备以后就 postman 搞一搞了,测试,mock 一起出
    py2ex
        93
    py2ex   12 天前
    @apifox 看回答看到一半就警惕了,看剩下的部分,果然!返回去按回复才发现 ID 早已预告🤣
    不过这个回复算是比较诚恳的推广
    Armour
        94
    Armour   12 天前
    给算进排期的话还是很愿意写的
    ptrees
        95
    ptrees   12 天前
    我觉得真的好用好好宣传就行了,这么套路给人很心机的感觉,反而让人警惕😅
    hewiefsociety
        96
    hewiefsociety   12 天前
    因为懒
    kkzxak47
        97
    kkzxak47   11 天前 via Android
    因为他们连接口都不想写。
    再就是不专业,其实 90%的写代码的人都不专业。
    关于   ·   帮助文档   ·   FAQ   ·   API   ·   我们的愿景   ·   广告投放   ·   感谢   ·   实用小工具   ·   3400 人在线   最高记录 5497   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 26ms · UTC 09:12 · PVG 17:12 · LAX 02:12 · JFK 05:12
    ♥ Do have faith in what you're doing.