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

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

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

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

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







    使用 markdown, 手工

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

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

    真是 不好吐槽
    54xavier
        53
    54xavier   261 天前
    swagger
    sannyzeng
        54
    sannyzeng   261 天前
    yapi
    fuyangyishi0
        55
    fuyangyishi0   261 天前
    没人用 RAP 吗
    Gunn27
        56
    Gunn27   261 天前
    guiling
        57
    guiling   261 天前
    yapi
    hjahgdthab750
        58
    hjahgdthab750   261 天前
    因为 go 没有便捷的 swagger 工具,我转 spring 这种插件成熟的框架了
    yang2048
        59
    yang2048   261 天前
    swagger 或者 knife4j
    YadongZhang
        60
    YadongZhang   261 天前
    RESTful API,只有我用 Postman 写文档吗。。。
    salenpeng
        61
    salenpeng   261 天前   ❤️ 1
    swag /:狗头
    hakr
        62
    hakr   261 天前
    @YadongZhang #60 俺也用...
    freebird1994
        63
    freebird1994   261 天前
    swagger + yapi
    liuw666
        64
    liuw666   261 天前
    写 protobuf 然后生成 swagger
    liuw666
        65
    liuw666   261 天前
    使用 protobuf 定义,只要想改接口参数,proto 就必须修改,swagger 肯定也是最新的
    ERRASYNCTYPE
        66
    ERRASYNCTYPE   261 天前
    实习生写
    asanelder
        67
    asanelder   261 天前
    @ERRASYNCTYPE #66 铁子, nb
    m1ch3ng
        68
    m1ch3ng   261 天前
    smart-doc,靠 javadoc 就能自动生成
    liuzhihang
        69
    liuzhihang   261 天前
    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   261 天前 via Android
    手写
    liuzhihang
        71
    liuzhihang   261 天前
    发不出来图…… 看链接吧 https://plugins.jetbrains.com/plugin/15305-doc-view
    noyidoit
        72
    noyidoit   261 天前
    postman......
    dcatfly
        73
    dcatfly   261 天前
    yapi 竟然有 1k+的 issue 没关闭,最近在用它内部的组件,代码写的一言难尽。。让我觉得这个项目还没死也是不容易。。
    vfxx
        74
    vfxx   261 天前
    @star7th 必须推荐 showdoc,用过的都说好。
    ArrayBuffer
        75
    ArrayBuffer   260 天前
    我是前端, 对我来说最好的还是 `swagger` / `graphql`; `swagger` 是比较成熟的, 但对于阅读者来说还是有些地方体验不是很好, 为此我写了个脚本 greasyfork.org/zh-CN/scripts/401581, `graphql` 我也写了 greasyfork.org/zh-CN/scripts/416677
    xcatliu
        76
    xcatliu   260 天前
    Swagger UI 感觉不是很好看,有没有其他替代?(除了 yapi )
    feitxue
        77
    feitxue   260 天前
    swagger 增强 ui 后的 knife4j,会舒服一点.
    zaul
        78
    zaul   260 天前
    语雀
    balabalaguguji
        79
    balabalaguguji   260 天前
    @xcatliu #76 易文档可以看下,真好用
    balabalaguguji
        80
    balabalaguguji   260 天前
    @vfxx #74 那肯定还没用过易文档
    vfxx
        81
    vfxx   260 天前
    我一直是用的 showdoc 私有化部署,易文档部署价格 8K,要不起。。。 易文档免费版竟然不支持导出
    liuliangsir
        82
    liuliangsir   253 天前
    @sss495088732 能问下,你用的是哪个 yapi docker 镜像
    smartdoc647
        84
    smartdoc647   127 天前   ❤️ 1
    smart-doc+torna,目前开源产品中国内最成熟的,科大讯飞和顺丰这些公司都在用,不是吹出来的。
    关于   ·   帮助文档   ·   API   ·   FAQ   ·   我们的愿景   ·   广告投放   ·   感谢   ·   实用小工具   ·   1195 人在线   最高记录 5497   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 25ms · UTC 23:50 · PVG 07:50 · LAX 15:50 · JFK 18:50
    ♥ Do have faith in what you're doing.