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

手写 api 文档写得想跑路了

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

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