V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
V2EX 提问指南
xoxo419
V2EX  ›  问与答

我有个朋友他这个 18 线小公司写 API 文档这个流程也太繁琐了

  •  2
     
  •   xoxo419 · 2022-10-11 08:26:54 +08:00 · 4155 次点击
    这是一个创建于 778 天前的主题,其中的信息可能已经有所发展或是发生改变。

    开发一个 API 功能的流程

    1. 写数据库字段描述文档
    2. 写代码模型(这个时候又要把字段描述复制一次到代码模型中)
    3. 写好逻辑开始测试, 然后又要把 model 字段复制到 postman 这类的接口调试工具中去调试
    4. 测试好后开始给前端写文档(这个时候又要把返回字段和参数再次复制字段描述)

    写一个 API ,重复 4 次,这也太繁琐了。。

    大家估计只写一次吧,有啥工具可以推荐下给他呢

    21 条回复    2022-10-11 14:32:07 +08:00
    SteinsGate
        1
    SteinsGate  
       2022-10-11 08:29:32 +08:00 via Android
    apifox
    xiao109
        2
    xiao109  
       2022-10-11 08:30:43 +08:00
    后三点可以通过 openapi 来描述,然后生成代码、导入到 postman 里自动生成接口 request 、生成接口文档。
    8520ccc
        3
    8520ccc  
       2022-10-11 08:35:01 +08:00 via iPhone
    不知道啥语言,我 golang 的话,现在最优方案

    数据库写一次 struct 此时给字段加上备注
    例如: 性别( 0 为男 1 为女)

    接口 req res 再写一次 struct
    此时可以复用数据库时的相同字段直接复制即可

    这时候只要开发完,文档自动好了
    datoujiejie221
        4
    datoujiejie221  
       2022-10-11 09:11:54 +08:00 via iPhone
    java 的话 mybatis 插件生成 model yapi 插件负责上传接口
    AlkTTT
        5
    AlkTTT  
       2022-10-11 09:22:26 +08:00   ❤️ 1
    idea 有个插件,Doc View ,我记得作者也在这里推广过。用起来很爽
    rocksolid
        6
    rocksolid  
       2022-10-11 09:29:18 +08:00
    轻舞飞扬
    securityCoding
        7
    securityCoding  
       2022-10-11 09:32:19 +08:00 via Android
    不如用 pb ?
    Rache1
        8
    Rache1  
       2022-10-11 09:44:56 +08:00
    直接设计数据库的时候,把 comment 加上,然后根据 comment 生成 1 、2 、然后再生成 openapi 导入到 POSTMAN ,或者和生成 POSTMAN 专属的集合 JSON ,就完成了 3 ,然后把 3 发给前端,不就有 4 了。
    zhenrong
        9
    zhenrong  
       2022-10-11 09:59:13 +08:00
    没必要,虽然写四次但是后面三次基本都是在复制粘贴了吧,工具虽然可以提高效率但不利于磨洋工摸鱼。
    ffw5b7
        10
    ffw5b7  
       2022-10-11 10:04:15 +08:00 via Android
    yapi
    HENQIGUAI
        11
    HENQIGUAI  
       2022-10-11 10:06:33 +08:00   ❤️ 1
    @rocksolid #6 你回复岔了 /t/885892
    rbe
        12
    rbe  
       2022-10-11 10:08:52 +08:00
    @zhenrong #9 并不是没必要。实操过就知道,如果要修改一个字段,要修改 4 个地方,总有改漏的时候,文档不一致维护就很麻烦
    wellsc
        13
    wellsc  
       2022-10-11 10:09:13 +08:00
    @HENQIGUAI hahaha
    jay4497
        14
    jay4497  
       2022-10-11 10:12:00 +08:00
    朋友:你可别,整天指着这个多算点工时摸鱼呢 doge;
    rocksolid
        15
    rocksolid  
       2022-10-11 10:14:43 +08:00
    @HENQIGUAI 是的 开着两个 tab 。。
    watzds
        16
    watzds  
       2022-10-11 10:16:02 +08:00
    是你自己吧 😆
    nothingistrue
        17
    nothingistrue  
       2022-10-11 10:43:59 +08:00
    上全套 UML 工具,然后又多出来了 UML 工具购买成本、学习成本、重构成本。

    工具选型或者过程选型,需要综合成本和收益综合考虑,百人以下的团队,数据库字段描述文档、给前端的标准文档(临时文档不算)这些都是成本收益比很低的东西,代码模型文档更是纯垃圾。
    tudou527
        18
    tudou527  
       2022-10-11 10:46:53 +08:00
    1 解决不了,2-4 可以看看: https://oneapi.app
    james2013
        19
    james2013  
       2022-10-11 11:27:25 +08:00
    确实很麻烦,如果 java 开发的话,数据库字段加上注释后,我一般是用 mybatis 插件生成实体和注释,使用 swagger,在 swagger 界面上调试,前端也是在这个界面上,自动带有注释
    hotsun168
        20
    hotsun168  
       2022-10-11 11:59:54 +08:00
    上上家的时候也有同样的问题,我给他们做了个开发环境的插件,自动根据数据库模型生成 DTO ,人工微调,然后根据 DTO 生成 Postman 的 JSON ,直接在 Postman 导入就完成所有接口的新建动作了。
    tim9527
        21
    tim9527  
       2022-10-11 14:32:07 +08:00
    我也是小公司,我都不写的。。。
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   1020 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 24ms · UTC 21:10 · PVG 05:10 · LAX 13:10 · JFK 16:10
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.