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

手写 api 文档写得想跑路了

  •  
  •   voidmnwzp ·
    NullpointerW · 2022-08-11 19:54:09 +08:00 via iPhone · 8972 次点击
    这是一个创建于 820 天前的主题,其中的信息可能已经有所发展或是发生改变。
    一个需求下来要提供给前端十几个 api ,以前用 swagger 一般都是先写 controller ,写完前端就能开发了,现在是定义完接口还得花半天时间写文档接口,这个过程真的无比痛苦,每写一个接口都得重复以下步骤:
    1 、复制接口 url
    2 、切换到 postman 写 request body
    3 、在接口 retrun 造的假数据,要是返回的数据结构简单还好,要是那种各种嵌套对象和 list 的结构那就更恶心了
    4 、发起请求,把 url 、请求 json 和返回 json copy 到文档上
    5 、写返回字段的备注
    这五步 每一步都是折磨,搞得每次开发干这种搬砖活就要搞半天
    62 条回复    2023-10-14 22:35:22 +08:00
    rxswift
        1
    rxswift  
       2022-08-11 19:55:17 +08:00
    有什么好办法吗
    pigmen
        2
    pigmen  
       2022-08-11 19:56:05 +08:00
    那为啥不用 swagger 呢?
    BeautifulSoap
        3
    BeautifulSoap  
       2022-08-11 19:58:20 +08:00 via Android
    还有人手写 swagger 的?。。。。。
    就算你项目没开始写代码,先随便用个框架简单定义好空的 controller 还有 DTO ,直接生成 swagger 不就好了,不至于手写 swagger
    voidmnwzp
        4
    voidmnwzp  
    OP
       2022-08-11 21:06:14 +08:00 via iPhone
    @BeautifulSoap 之前一家是 swagger 很方便 这家不让用 swagger 必须手写 api 文档
    issakchill
        5
    issakchill  
       2022-08-11 21:10:36 +08:00
    搞个 yapi 无侵入的输出吧 手写也太累了吧
    freebird1994
        6
    freebird1994  
       2022-08-11 21:27:02 +08:00 via Android
    yapi 手填文档,apipost 和 postman 一样做接口自测,可以根据返回的数据结构生成文档(自己写注释),应该都比你现在效率高些而且好维护些
    DOLLOR
        7
    DOLLOR  
       2022-08-11 21:31:54 +08:00 via Android
    我觉得你对接的前端同事面对这样的文档,也会跟你一样难受。
    我觉得你们可以学一下 typescript 的 interface 语法,用来当作对象字段描述语言,表达那些复杂的对象会方便一些,前段同事也能方便对接字段。
    zhuangzhuang1988
        8
    zhuangzhuang1988  
       2022-08-11 21:35:48 +08:00   ❤️ 9
    postman 肯定是要走一遍的
    我前端 接过 postman 没走一遍的 后端 api
    每次都有 api 问题, 一问后端, 自己都没测试过.
    Vegetable
        9
    Vegetable  
       2022-08-11 21:41:10 +08:00
    ...写空 Controller 先生成文档不行吗
    winglight2016
        10
    winglight2016  
       2022-08-11 22:16:58 +08:00
    swagger 也支持自定义模板的,为啥不自己定制一下?实在不行自己解析一下 api json ,用模板生成一下
    jack778
        11
    jack778  
       2022-08-11 22:27:06 +08:00   ❤️ 1
    apifox 自动生成 api 在线共享,爽的一比,打灰机
    v2eb
        12
    v2eb  
       2022-08-11 22:44:41 +08:00 via Android
    有根据 javadoc 生成文档的。smart-doc
    hsuyeung
        13
    hsuyeung  
       2022-08-11 22:55:27 +08:00
    knife4j 的文档导出功能,导出成 word 应该可以吧,我试了下,感觉格式还行
    hsuyeung
        14
    hsuyeung  
       2022-08-11 22:56:12 +08:00
    @hsuyeung 也有 HTML 、Markdown 、OpenAPI 格式的
    dingyaguang117
        15
    dingyaguang117  
       2022-08-11 23:04:06 +08:00
    stoplight 了解一下
    Leoooooo
        16
    Leoooooo  
       2022-08-11 23:12:48 +08:00
    花一天时间写个自动化工具,只需要手动补充文档释义。节省未来一大半精力,还有成就感。
    neochen13
        17
    neochen13  
       2022-08-11 23:26:49 +08:00
    有啥现成好法子不
    bojackhorseman
        18
    bojackhorseman  
       2022-08-11 23:49:57 +08:00 via iPhone
    对接的前端大概也很难受,现在做的项目接口文档用的 word ,看着很难受,而且没有用等宽字体 l 和 I 都分不清😅,只好全局替换成等宽字体。
    iseki
        19
    iseki  
       2022-08-12 00:32:53 +08:00 via Android
    要么写代码生成文档,要么写文档生成代码,既写代码又写文档这的确烦人,时间一久就容易代码文档对不上
    kkeep
        20
    kkeep  
       2022-08-12 01:08:17 +08:00 via Android
    我有解决办法,半夜起来加班,在前端开始做之前,接口就 ready
    MarioLuo
        21
    MarioLuo  
       2022-08-12 07:53:38 +08:00 via Android
    如果是用的 spring ,可以用这个 Idea 插件,从标准 Java doc 生成代码: https://github.com/jetplugins/yapix
    NPC666
        22
    NPC666  
       2022-08-12 08:19:35 +08:00 via Android
    我们是手写 swagger ,一个 yml 文件上万行,复制粘贴的时候 IDE 都要卡一会儿😅
    xiao109
        23
    xiao109  
       2022-08-12 08:30:25 +08:00
    swagger 连他亲爹都放弃了吧
    bitmin
        24
    bitmin  
       2022-08-12 08:31:11 +08:00 via Android
    yapi github 的 readme 上推荐了一些 idea 插件,我最近在用 easy-yapi 这个插件。因为写着 easy 就点开看了。代码无侵入,通过 Javadoc API 生成文档。可以导出到 yapi postman 等。还提供了一些增强的配置,可以配置回调。

    我打算提交代码到 gitlab 的时候自动执行工具生成导出到 yapi ,有没有这样的工具?
    dfkjgklfdjg
        25
    dfkjgklfdjg  
       2022-08-12 08:43:00 +08:00
    考虑一下 yapi 这种可以生成接口文档的东西?
    leeUp
        26
    leeUp  
       2022-08-12 09:01:18 +08:00
    可以自己本地用 swagger 生成,然后用 postman 导入,这样就可以了
    liuzhihang
        27
    liuzhihang  
       2022-08-12 09:07:01 +08:00 via iPhone   ❤️ 1
    试试我写的 idea 插件: Doc View
    littleMouse
        28
    littleMouse  
       2022-08-12 09:22:40 +08:00
    为啥我们是前端写 api 文档啊,好痛苦┭┮﹏┭┮
    C603H6r18Q1mSP9N
        29
    C603H6r18Q1mSP9N  
       2022-08-12 09:24:32 +08:00
    写完自己不测试一遍?
    没有测试测接口?
    xuanbg
        30
    xuanbg  
       2022-08-12 09:30:07 +08:00
    手写 API 文档就是在模版上做几道填空题嘛,好写的很!而且我都是先把文档写好再开始写代码的。
    still97
        31
    still97  
       2022-08-12 09:37:43 +08:00
    @xuanbg 有没有可能,你的结构都很简单?我这一份简单的报告三四百行返回数据,各种嵌套数据格式,真没感觉到你说的这种简单。
    cccssss
        32
    cccssss  
       2022-08-12 09:39:31 +08:00
    曾经我也很痛苦,然后我花了大半天用 javaparser-core 写了一个获取 java doc 的小脚本就搞定了,一共 400 行代码
    xuboying
        33
    xuboying  
       2022-08-12 09:41:37 +08:00
    手工写的文档用户一般是不信任的。。。。
    xuboying
        34
    xuboying  
       2022-08-12 09:42:18 +08:00
    @xuboying #33 文档-> API 文档
    aboat365
        35
    aboat365  
       2022-08-12 09:45:28 +08:00   ❤️ 1
    对于不让使用 Swagger 、不让使用 Lombok 、不让使用 IDEA ,不让使用方便程序开发,而又讲不出有力禁止理由的规定,都是耍流氓。程序的本质是什么?就是解放劳动力,提高生产力,把手动工作,编排成机器自动的工作。一切程序可以自动替代的,都应该由程序来做!
    alen0206
        36
    alen0206  
       2022-08-12 10:04:36 +08:00
    如果是用的 Yapi 可以用 YapiUpload 插件 接口定义写完就能上传
    MarioLuo
        37
    MarioLuo  
       2022-08-12 10:30:55 +08:00   ❤️ 1
    @bitmin smart-doc maven 插件 自己扩展下上传到 yapi 可以实现,但是有个问题,多分支开发怎么弄,yapi 本身的文档管理功能没有多分支,多版本的概念
    CodeCodeStudy
        38
    CodeCodeStudy  
       2022-08-12 10:37:39 +08:00
    做完不测试吗,测试的话 postman 的流程也要走一遍吧
    NoKey
        39
    NoKey  
       2022-08-12 10:40:21 +08:00
    你完全可以搞个 idea ,然后在里面写 controller 及各参数,要么用 swagger ,要么 idea 加一些插件,能生成 request body 的 json 结构,写文档也快。手写 api ,也不是完全不写代码,比如要 uml 图,你真的手写去画么? idea 先写一些伪代码,自动生成了复制啊
    RainCats
        40
    RainCats  
       2022-08-12 10:43:55 +08:00
    用模板技术去生成,提前写好模板就好了
    shalk
        41
    shalk  
       2022-08-12 10:47:56 +08:00
    自己想办法生成一下,再稍微改改
    18601294989
        42
    18601294989  
       2022-08-12 10:51:28 +08:00
    swagger 导出到 postman 就好了吧
    lpbname777
        43
    lpbname777  
       2022-08-12 10:57:40 +08:00
    @zhuangzhuang1988 雾草!后端接口盲写 同感
    aicfe
        44
    aicfe  
       2022-08-12 11:26:36 +08:00
    我用 yapi + idea 上安装 easyYapi 插件 一键导出 还能给前端 mock
    zhuangzhuang1988
        45
    zhuangzhuang1988  
       2022-08-12 11:26:42 +08:00 via Android
    @lpbname777 遇到太多了,前端当测试,最基础的数据都过不了
    edward1987
        46
    edward1987  
       2022-08-12 11:27:40 +08:00
    无论输出是什么,都要自动化
    xuxuzhaozhao
        47
    xuxuzhaozhao  
       2022-08-12 13:18:43 +08:00
    了解一下 ApiPost ,爽得呀丕
    potatowish
        48
    potatowish  
       2022-08-12 13:43:37 +08:00 via iPhone
    不让用 swagger 估计是侵入代码层了,考虑下无侵入的方式,比如说 smart-doc ,或者是基于单元测试的,sping rest doc 离线文档
    nothingistrue
        49
    nothingistrue  
       2022-08-12 13:53:23 +08:00
    目测你在移动、联通系统集成或者类似这样的企业里面做外包,或者是对日外包。死板的 CMMI 规范,一行代码一百页文档,自己不想干就让外包的人干。
    fzdwx
        50
    fzdwx  
       2022-08-12 14:14:44 +08:00
    可以试试 easy yapi 导出 md 文档
    StarkWhite
        51
    StarkWhite  
       2022-08-12 14:19:20 +08:00
    fb 的 graphql 了解下,文档不用写了
    https://v2ex.com/t/589138?p=2#reply137
    voidmnwzp
        52
    voidmnwzp  
    OP
       2022-08-12 15:47:14 +08:00 via iPhone
    @nothingistrue 并不是 是个 to c 互联网企业 反而之前是在做电信项目的公司用的 swagger
    hetal
        53
    hetal  
       2022-08-12 15:48:26 +08:00
    protobuf 不香么,配合 doc 工具自动生成 api 文档,再加一个 restful 网关就行了
    tiedan
        54
    tiedan  
       2022-08-12 17:08:50 +08:00
    我的关注点是一个需求十几个新 api 。。。 这么恐怖吗
    gzlixiaochao555
        55
    gzlixiaochao555  
       2022-08-12 17:26:30 +08:00
    可以试试 Eolink ,通过 swagger.json 直接生成接口文档,支持在线测试
    watzds
        56
    watzds  
       2022-08-12 18:13:06 +08:00
    IDEA 装 EasyApi 插件,写完 Controller 能直接同步到 yapi, postman 等地方,很方便啊
    pengtdyd
        57
    pengtdyd  
       2022-08-12 21:12:02 +08:00
    S 13 的技术管理,就是有这些奇葩的事情。
    ClarkAbe
        58
    ClarkAbe  
       2022-08-13 18:33:31 +08:00 via Android
    我司也是我这边五个大模块将近四百个接口前几天主管说用手写文档还要一个月内开发完....我直接就怼回去了
    voidmnwzp
        59
    voidmnwzp  
    OP
       2022-08-15 00:43:12 +08:00 via iPhone
    @ClarkAbe 这种还不如跑了
    xuanbg
        60
    xuanbg  
       2022-08-15 11:29:46 +08:00
    @still97 对象嵌套不是很正常的嘛,问题是你要怎么去描述。我就是把所有对象都用表格描述,表格里面有一列叫类型,那么某个字段该是什么类型就加个跳转指向那个类型的表格就好了呀。
    一般这个没人看的,因为我提供了示例数据,包括入参和返回数据。前端看到返回数据的示例,就知道接口返回是什么。只要照抄我提供的参数,就能返回期望的数据。
    ClarkAbe
        61
    ClarkAbe  
       2022-08-16 14:20:48 +08:00 via Android
    @voidmnwzp 我也想但是小城找新的太麻烦了
    ricebna
        62
    ricebna  
       2023-10-14 22:35:22 +08:00
    对于接口文档的编写, 我觉得用任何工具都会有效率耗损。包括 yapi ,postman ,还有注释类的 swagger 。
    接口文档特别是内部用的并且是前端用的,95%的情况就是一个简单的输出与输入,主要工作是描述清楚字段结构,主要目的是与前端达成沟通以及存档的作用,并不需要多么标准化。
    而各种工具,无论是界面类的还是注释自动转换类的, 都需要遵照特定规范,按要求去填写。
    点击一个输入框或是写上特定注释标记都需要额外的时间与心智消耗,这些精准规范其实没必要, 并且他们(特别是国产工具)都经不起时间的变化, 另外维护更新工作也是一个反人性大家都不想做的事情。

    所以我在想在写文档的效率方面, 直接用最简单的文本是最方便的,直接在代码编辑器写注释文本,不需要遵照特定注释规范, 特别是输出参数比较多, 层级也多, 直接用所见即所得的 json 文本本身做为描述是最简单的。无需担心格式出错, 维护更新也在相同的地方, 没有割裂感. 并且他们的经得起时间的沉淀 (越简单的东西, 他们的存在度和稳定性就越高, 日后你想要转换成任何文档形式都可以. 这也是我对于笔记应用的一个观念转变: 从印象笔记到后来直接用 vscode 写 md, 到现在 md 只不过是一个文件后缀而实际很少用它的语法了, 而同步功能直接用谷歌云盘同步目录, git 不定期备份. 大道至简)

    然后把我们写得不那么标准的简化注释用 ChatGPT 转换成勉强标准的结构化文档,它就适合做这类不精准的东西,还有纠错能力。
    我试过了,它转换成的 postman 导入文件居然是对的,我还担心这种事情它一般会出错,不过凡涉及代码的东西最好不用,有时出错给它排错的时间不值。
    [Imgur]( )
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   1830 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 39ms · UTC 16:36 · PVG 00:36 · LAX 08:36 · JFK 11:36
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.