• 请不要在回答技术问题时复制粘贴 AI 生成的内容
asanelder
V2EX  ›  程序员

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

  •  1
     
  •   asanelder · Mar 10, 2021 · 13424 views
    This topic created in 2080 days ago, the information mentioned may be changed or developed.
    java 写的 web 服务, 要给前端提供接口文档, 问下大家都是怎么生成的?
    现在业内实践用的都是啥?
    Supplement 1  ·  Mar 10, 2021
    看来主流还是 swagger 和 yapi 啊

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

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







    使用 markdown, 手工

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

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

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