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

API 文档大家是怎么生成的?

  •  1
     
  •   asanelder · 2021-03-10 09:39:25 +08:00 · 10904 次点击
    这是一个创建于 1114 天前的主题,其中的信息可能已经有所发展或是发生改变。
    java 写的 web 服务, 要给前端提供接口文档, 问下大家都是怎么生成的?
    现在业内实践用的都是啥?
    第 1 条附言  ·  2021-03-10 17:33:29 +08:00
    看来主流还是 swagger 和 yapi 啊

    俺看了一下, 俺的服务不到 10 个接口, 也很简单

    所以, 最终, 俺用的方式是







    使用 markdown, 手工

    感谢铁子们推荐, 等接口复杂了, 再研究你们的工具
    84 条回复    2021-07-22 23:09:17 +08:00
    alanhe421
        1
    alanhe421  
       2021-03-10 09:41:47 +08:00
    swagger
    sunziren
        2
    sunziren  
       2021-03-10 09:49:18 +08:00
    用过楼上的,挺好的
    gageshan
        3
    gageshan  
       2021-03-10 09:49:53 +08:00   ❤️ 1
    knightdf
        4
    knightdf  
       2021-03-10 09:50:51 +08:00
    openapi, swagger
    wolfie
        5
    wolfie  
       2021-03-10 09:51:31 +08:00
    md 手写,生成的除了自己很难看,而且涉及到字段改动怎么标注。
    lungank
        6
    lungank  
       2021-03-10 09:52:14 +08:00
    swagger
    rationa1cuzz
        7
    rationa1cuzz  
       2021-03-10 09:55:15 +08:00
    难道就我一个人手写吗?
    hanssx
        8
    hanssx  
       2021-03-10 09:56:48 +08:00
    如果 python 的话,fastapi 很不错。
    zlhsvc
        9
    zlhsvc  
       2021-03-10 09:56:55 +08:00
    手写,之前用过脚本总觉得差了点
    yiqiao
        10
    yiqiao  
       2021-03-10 09:57:06 +08:00
    swagger 能够快速生成。
    showdoc
    acmore
        11
    acmore  
       2021-03-10 09:57:33 +08:00
    swagger
    Java 生态下也可以考虑 Spring Rest Docs
    balabalaguguji
        12
    balabalaguguji  
       2021-03-10 09:59:25 +08:00
    可以用易文档编写 https://easydoc.xyz ,它也可以一键生成文档,也可以从注释生成文档。预览效果: https://www.easydoc.xyz/s/17790664

    截图
    https://i.loli.net/2021/03/10/jVQdKMkJ4FPevui.png
    liuzhaowei55
        13
    liuzhaowei55  
       2021-03-10 10:01:18 +08:00 via iPhone
    手写
    bigpigeon
        14
    bigpigeon  
       2021-03-10 10:03:12 +08:00
    swagger
    bigpigeon
        15
    bigpigeon  
       2021-03-10 10:04:09 +08:00
    写了一个通过 go 框架生成 swagger 代码的 api,只要实现 api 就能自动生成 swagger
    SjwNo1
        16
    SjwNo1  
       2021-03-10 10:06:49 +08:00
    手写+1
    sss495088732
        17
    sss495088732  
       2021-03-10 10:10:15 +08:00
    yapi docker 手写
    jowan
        18
    jowan  
       2021-03-10 10:14:20 +08:00
    swag
    zhaorunze
        19
    zhaorunze  
       2021-03-10 10:16:42 +08:00
    我还以为手写了个框架,仔细一想,可能是手写文档。。。
    ghouleztt
        20
    ghouleztt  
       2021-03-10 10:19:02 +08:00
    swagger
    Molita
        21
    Molita  
       2021-03-10 10:20:22 +08:00
    swagger 然后 用 redoc 展示
    15190049162
        22
    15190049162  
       2021-03-10 10:20:45 +08:00
    swagger+插件直接变 doc
    mcfog
        23
    mcfog  
       2021-03-10 10:28:27 +08:00
    重要的不是怎么生成,而是数据源在哪里,怎么管理
    h82258652
        24
    h82258652  
       2021-03-10 10:29:44 +08:00
    swagger,部分生成不了的用 docfx
    oneend
        25
    oneend  
       2021-03-10 10:32:23 +08:00
    只有我用 gitbook 吗?
    www5070504
        26
    www5070504  
       2021-03-10 10:34:11 +08:00
    swagger 只要增加几行注释 很好用..
    a62527776a
        27
    a62527776a  
       2021-03-10 10:36:22 +08:00
    apidoc
    Rekkles
        28
    Rekkles  
       2021-03-10 10:36:49 +08:00
    yapi
    star7th
        29
    star7th  
       2021-03-10 10:37:34 +08:00   ❤️ 3
    journalistFromHK
        30
    journalistFromHK  
       2021-03-10 10:48:07 +08:00
    上一家公司,老板写 java,啥是文档?不存在的,自己去看 controller 吧
    so1n
        31
    so1n  
       2021-03-10 10:49:02 +08:00
    自己写了一个库来自动生成 https://github.com/so1n/pait
    henryhu
        32
    henryhu  
       2021-03-10 11:18:24 +08:00
    apidoc
    UN2758
        33
    UN2758  
       2021-03-10 11:20:37 +08:00
    @hanssx #8 我记得 fastapi 用的也是 swagger
    KisekiRemi
        34
    KisekiRemi  
       2021-03-10 11:21:41 +08:00
    对接的给我一个 swagger
    cat007
        35
    cat007  
       2021-03-10 11:25:34 +08:00
    swagger+yapi
    AngryPanda
        36
    AngryPanda  
       2021-03-10 11:27:09 +08:00
    md 手写 、YAPI
    evam
        37
    evam  
       2021-03-10 11:31:20 +08:00
    postman 自己调试接口,然后 postman 分享,coding 自动生成
    egfegdfr
        38
    egfegdfr  
       2021-03-10 11:39:48 +08:00
    smart-doc
    感觉 swagger 的侵入性太强了
    jorneyr
        39
    jorneyr  
       2021-03-10 11:41:09 +08:00   ❤️ 1
    不喜欢 swagger 这种污染源码的工具,更喜欢用 yApi 这种类似的工具进行管理。
    xuanbg
        40
    xuanbg  
       2021-03-10 11:54:45 +08:00
    @wolfie md 手写+1,也就是模版上面复制粘贴,一点都不费事。swagger 实在是太丑
    monkeyWie
        41
    monkeyWie  
       2021-03-10 12:01:01 +08:00
    swagger 然后自动同步到 yapi
    scxiazi
        42
    scxiazi  
       2021-03-10 12:07:31 +08:00
    restdoc
    putaozhenhaochi
        43
    putaozhenhaochi  
       2021-03-10 12:16:20 +08:00
    借楼问下,各位是先定义接口 还是先写代码
    MarioLuo
        44
    MarioLuo  
       2021-03-10 12:33:16 +08:00
    YapiIdeaUploadPlugin IDEA 插件基于 JavaDoc 注释生成文档,上传到 yapi 中.
    xnotepad
        45
    xnotepad  
       2021-03-10 13:05:58 +08:00
    自己写了个 https://apidoc.tools
    chogath
        46
    chogath  
       2021-03-10 13:25:13 +08:00
    swagger + yapi,永远滴神
    newmlp
        47
    newmlp  
       2021-03-10 13:31:18 +08:00
    md 手写
    offswitch
        48
    offswitch  
       2021-03-10 13:50:56 +08:00
    @putaozhenhaochi 通常的说法是先写定义再写代码,不过大部分公司根本就没这要求,爱咋咋
    alienx717
        49
    alienx717  
       2021-03-10 13:57:36 +08:00
    md 手写
    XCFOX
        50
    XCFOX  
       2021-03-10 14:09:00 +08:00
    目前用过最舒服的是 GraphQL 。文档和接口无缝结合。接口还是强类型的。前端能直接根据 graphql 接口地址生成接口类型
    20200924
        51
    20200924  
       2021-03-10 14:18:37 +08:00
    作为前端人员,感觉看 yapi 比看 swagger 舒服很多
    justin2018
        52
    justin2018  
       2021-03-10 14:44:07 +08:00
    每次 API 有啥修改 就发一份 word 文档

    真是 不好吐槽
    54xavier
        53
    54xavier  
       2021-03-10 14:44:36 +08:00
    swagger
    sannyzeng
        54
    sannyzeng  
       2021-03-10 14:59:40 +08:00
    yapi
    fuyangyishi0
        55
    fuyangyishi0  
       2021-03-10 15:02:23 +08:00
    没人用 RAP 吗
    Gunn27
        56
    Gunn27  
       2021-03-10 15:06:47 +08:00
    guiling
        57
    guiling  
       2021-03-10 15:16:48 +08:00
    yapi
    qW7bo2FbzbC0
        58
    qW7bo2FbzbC0  
       2021-03-10 15:23:28 +08:00
    因为 go 没有便捷的 swagger 工具,我转 spring 这种插件成熟的框架了
    yang2048
        59
    yang2048  
       2021-03-10 15:39:03 +08:00
    swagger 或者 knife4j
    YadongZhang
        60
    YadongZhang  
       2021-03-10 15:52:02 +08:00
    RESTful API,只有我用 Postman 写文档吗。。。
    salenpeng
        61
    salenpeng  
       2021-03-10 15:57:22 +08:00   ❤️ 1
    swag /:狗头
    hakr
        62
    hakr  
       2021-03-10 16:07:14 +08:00
    @YadongZhang #60 俺也用...
    freebird1994
        63
    freebird1994  
       2021-03-10 16:17:52 +08:00
    swagger + yapi
    liuw666
        64
    liuw666  
       2021-03-10 16:45:54 +08:00
    写 protobuf 然后生成 swagger
    liuw666
        65
    liuw666  
       2021-03-10 16:47:59 +08:00
    使用 protobuf 定义,只要想改接口参数,proto 就必须修改,swagger 肯定也是最新的
    ERRASYNCTYPE
        66
    ERRASYNCTYPE  
       2021-03-10 17:20:09 +08:00
    实习生写
    asanelder
        67
    asanelder  
    OP
       2021-03-10 17:32:09 +08:00
    @ERRASYNCTYPE #66 铁子, nb
    m1ch3ng
        68
    m1ch3ng  
       2021-03-10 18:32:51 +08:00
    smart-doc,靠 javadoc 就能自动生成
    liuzhihang
        69
    liuzhihang  
       2021-03-10 19:22:57 +08:00
    IDEA 插件 Doc View 纯 markdown 。不知道能不能满足你的需求。也欢迎 v2 小伙伴提 PR

    https://github.com/liuzhihang/doc-view

    ![aF2vk5-L5pmGt]( https://cdn.jsdelivr.net/gh/liuzhihang/oss/pic/article/aF2vk5-L5pmGt.png)
    Cbdy
        70
    Cbdy  
       2021-03-10 19:37:33 +08:00 via Android
    手写
    liuzhihang
        71
    liuzhihang  
       2021-03-10 19:51:11 +08:00
    发不出来图…… 看链接吧 https://plugins.jetbrains.com/plugin/15305-doc-view
    noyidoit
        72
    noyidoit  
       2021-03-10 20:02:41 +08:00
    postman......
    dcatfly
        73
    dcatfly  
       2021-03-10 21:54:48 +08:00
    yapi 竟然有 1k+的 issue 没关闭,最近在用它内部的组件,代码写的一言难尽。。让我觉得这个项目还没死也是不容易。。
    vfxx
        74
    vfxx  
       2021-03-10 21:55:19 +08:00
    @star7th 必须推荐 showdoc,用过的都说好。
    ArrayBuffer
        75
    ArrayBuffer  
       2021-03-11 09:15:55 +08:00
    我是前端, 对我来说最好的还是 `swagger` / `graphql`; `swagger` 是比较成熟的, 但对于阅读者来说还是有些地方体验不是很好, 为此我写了个脚本 greasyfork.org/zh-CN/scripts/401581, `graphql` 我也写了 greasyfork.org/zh-CN/scripts/416677
    xcatliu
        76
    xcatliu  
       2021-03-11 09:34:59 +08:00
    Swagger UI 感觉不是很好看,有没有其他替代?(除了 yapi )
    feitxue
        77
    feitxue  
       2021-03-11 09:54:18 +08:00
    swagger 增强 ui 后的 knife4j,会舒服一点.
    zaul
        78
    zaul  
       2021-03-11 14:53:14 +08:00
    语雀
    balabalaguguji
        79
    balabalaguguji  
       2021-03-11 18:01:11 +08:00
    @xcatliu #76 易文档可以看下,真好用
    balabalaguguji
        80
    balabalaguguji  
       2021-03-11 18:02:15 +08:00
    @vfxx #74 那肯定还没用过易文档
    vfxx
        81
    vfxx  
       2021-03-11 20:32:18 +08:00
    我一直是用的 showdoc 私有化部署,易文档部署价格 8K,要不起。。。 易文档免费版竟然不支持导出
    liuliangsir
        82
    liuliangsir  
       2021-03-18 10:13:57 +08:00
    @sss495088732 能问下,你用的是哪个 yapi docker 镜像
    sss495088732
        83
    sss495088732  
       2021-03-18 11:39:15 +08:00
    smartdoc647
        84
    smartdoc647  
       2021-07-22 23:09:17 +08:00   ❤️ 1
    smart-doc+torna,目前开源产品中国内最成熟的,科大讯飞和顺丰这些公司都在用,不是吹出来的。
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   4484 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 31ms · UTC 10:08 · PVG 18:08 · LAX 03:08 · JFK 06:08
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.