V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
The Go Programming Language
http://golang.org/
Go Playground
Go Projects
Revel Web Framework
DoctorCat
V2EX  ›  Go 编程语言

注解的方式生成 swagger 文档太麻烦,有没有 Go 模块类似 Python FastAPI 的自动生成文档的机制?

  •  
  •   DoctorCat · 2020-11-26 13:08:41 +08:00 · 4928 次点击
    这是一个创建于 1219 天前的主题,其中的信息可能已经有所发展或是发生改变。
    第 1 条附言  ·  2020-11-26 14:11:15 +08:00
    请别建议我手撸 markdown 之类的了,写了 10 年代码了不想继续手写 doc 了哦
    第 2 条附言  ·  2020-11-26 16:39:42 +08:00
    想实现的是 RESTful 接口,而不是 RPC 接口。
    第 3 条附言  ·  2021-07-07 12:07:11 +08:00
    虽然不是很满足预期,但是相对能减少些工作量,可以试试: https://github.com/swaggo/swag/blob/master/README_zh-CN.md
    42 条回复    2020-11-27 14:07:26 +08:00
    xuanbg
        1
    xuanbg  
       2020-11-26 13:10:41 +08:00
    手写 MD 文档就不麻烦了,复制-粘贴改一改就好,效率飞起
    qW7bo2FbzbC0
        2
    qW7bo2FbzbC0  
       2020-11-26 13:23:45 +08:00   ❤️ 1
    用 c# 或者 spring 多好,django 的 swagger 都不是很方便,因为这个原因弃用 go 做 web 服务
    charmToby
        3
    charmToby  
       2020-11-26 13:44:42 +08:00
    同求,有类似机制的,楼主记得艾特我。
    lingxi27
        4
    lingxi27  
       2020-11-26 14:00:41 +08:00   ❤️ 2
    换种思路,文档->代码
    DoctorCat
        5
    DoctorCat  
    OP
       2020-11-26 14:08:36 +08:00
    @lingxi27
    @xuanbg

    要的就是 swagger 在线发请求的测试功能,回到原始 doc 上那当然就不会有这个问题了…建议我手写 doc 仿佛在跟我说蒸汽机不好搞,还是继续坐马车吧 🤦‍♂️
    DoctorCat
        6
    DoctorCat  
    OP
       2020-11-26 14:12:12 +08:00
    @hjahgdthab750 Python 的话 FastAPI 可以自动生成,不需要人肉介入。
    qW7bo2FbzbC0
        7
    qW7bo2FbzbC0  
       2020-11-26 14:17:26 +08:00   ❤️ 1
    @DoctorCat #6 fastapi 不能像 flask django 那样直接用 py 文件启动吧,好像要在系统上装什么来着
    qW7bo2FbzbC0
        8
    qW7bo2FbzbC0  
       2020-11-26 14:20:09 +08:00
    @hjahgdthab750 #7 没有超级用户权限,我选择绕开 fastapi,本来还是挺不错的项目
    TangMonk
        9
    TangMonk  
       2020-11-26 14:21:45 +08:00 via iPhone
    Ruby 的 grape 配合 swagger 异常好用,全自动生成,连注释都不写
    haitaotao
        10
    haitaotao  
       2020-11-26 14:23:09 +08:00 via iPhone
    如果是 api 的建议先使用 protobuf 等 idl 描述,再动生成文档和代码。

    我们也是苦文档不更新久矣。最后搞了个[sniper 框架]( https://github.com/bilibili/sniper),具体的设计思路可以参考[这篇文章]( https://zhuanlan.zhihu.com/p/69029677)。在生产环境跑了两年多了,效果还不错。
    charmToby
        11
    charmToby  
       2020-11-26 14:24:16 +08:00
    @hjahgdthab750 FastAPI 只需要安装 uvicorn 就可以直接 py 文件启动了。
    wzw
        12
    wzw  
       2020-11-26 14:24:34 +08:00
    qW7bo2FbzbC0
        13
    qW7bo2FbzbC0  
       2020-11-26 14:27:13 +08:00
    @charmToby #11 对对,线上没有 uvicorn,也没有安装的权限
    siteshen
        14
    siteshen  
       2020-11-26 14:47:10 +08:00
    有几年没用 go 了,看到这个话题,回顾一下在 go 项目中使用 swagger 历程。
    注:我也一直讨厌写不必要的 API 文档,尤其是 API 输入、输出格式等本应该能自动生成的文档。

    1. 最初是自己写的代码,根据 request, response 对象生成 swagger.json 文件( python 也自己写过……):
    https://www.v2ex.com/t/390148?p=1#r_4746014
    2. 后来某个项目使用过 https://github.com/MarkSonghurst/swag (印象中某些 feature 支持不够好,我还改过少量代码)
    3. 另外看到其他 v 友选择过 https://github.com/Tencent/APIJSON,也许以后会尝试?
    https://v2ex.com/t/556593?p=2#r_7208890
    reus
        15
    reus  
       2020-11-26 14:59:06 +08:00 via Android   ❤️ 1
    学习下标准库里 go/ast go/types 几个包,自己写一个就行,一两百行完事的程序,自己需要什么就写什么,何必到处找,你找到也未必合用。
    herofire
        16
    herofire  
       2020-11-26 15:12:52 +08:00
    smartdoc?
    Biebe
        17
    Biebe  
       2020-11-26 15:37:21 +08:00 via iPhone
    用 protobuf 描述借口,protoc swagger 插件自动生成
    tiedan
        18
    tiedan  
       2020-11-26 15:46:01 +08:00
    protobuf
    lingxi27
        19
    lingxi27  
       2020-11-26 15:59:19 +08:00
    @DoctorCat

    你可能没完全明白我的意思,要不看看这个能不能帮到你
    lingxi27
        20
    lingxi27  
       2020-11-26 16:00:04 +08:00
    Rwing
        21
    Rwing  
       2020-11-26 16:01:19 +08:00
    考虑下 c#,直接把代码注释生成 swagger 😊
    janxin
        22
    janxin  
       2020-11-26 16:30:28 +08:00
    zqx
        23
    zqx  
       2020-11-26 16:35:16 +08:00 via Android
    先写文档,再开发,就不慢了
    DoctorCat
        24
    DoctorCat  
    OP
       2020-11-26 16:38:22 +08:00
    @lingxi27 我们理解的“自动”这项能力,不是同一种,我要的是不需要写代码注释的生成框架。

    @reus 你的提议很好,不过我就是想先看看有没有可以百白嫖的代码
    yuan434356430
        25
    yuan434356430  
       2020-11-26 16:42:37 +08:00
    用 javaparser 静态分析代码,自动生成 Swagger 注解,我这么写过,不过只是生成了简单一点的,因为有些字段和方法是没有注释的
    yuan434356430
        26
    yuan434356430  
       2020-11-26 16:44:14 +08:00
    因为 swagger 的注解内容都是可以从已有的代码里读取到的
    DoctorCat
        27
    DoctorCat  
    OP
       2020-11-26 16:44:24 +08:00
    @siteshen 不太喜欢 APIJSON 接管 ORM
    siteshen
        28
    siteshen  
       2020-11-26 16:56:17 +08:00
    @DoctorCat 我用 go 写 API,没用过 framework,都是用的 library,自己手写 model + generate 通用的 model 级别的 API 。
    听你这么说 APIJSON 还会接管 ORM,应该是 framework 了。
    meshell
        29
    meshell  
       2020-11-26 17:01:08 +08:00
    用 go 我还是建议手写 markdown....
    sprite82
        30
    sprite82  
       2020-11-26 17:30:17 +08:00
    推荐个 apifox 功能方面挺好的,mock swagger,压测 都有,但是貌似有 cpu 占用的问题,如果有安全要求的话就别用了
    DoctorCat
        31
    DoctorCat  
    OP
       2020-11-26 17:31:49 +08:00
    @siteshen APIJSON ? 可能我不太熟这个操作。
    jiyingze
        32
    jiyingze  
       2020-11-26 18:13:13 +08:00
    smart-doc 可以根据源码注释生成文档。
    DoctorCat
        33
    DoctorCat  
    OP
       2020-11-26 20:05:16 +08:00
    @jiyingze 你确定说的是支持 Go 语言的产物?
    saberlong
        34
    saberlong  
       2020-11-26 22:35:28 +08:00 via Android
    我也是用 golang 自带 ast 针对性写的
    lidashuang
        35
    lidashuang  
       2020-11-27 11:49:23 +08:00
    lidashuang
        36
    lidashuang  
       2020-11-27 11:49:47 +08:00
    @charmToby Graphql 也可以考虑
    lidashuang
        37
    lidashuang  
       2020-11-27 11:50:02 +08:00
    @meshell 手写 你不累吗
    meshell
        38
    meshell  
       2020-11-27 12:00:04 +08:00
    @lidashuang 还好呀。说实话,go 里面写注释,然后生成还没有手写 markdown 复制粘贴快.
    TransAM
        39
    TransAM  
       2020-11-27 12:44:13 +08:00 via Android
    python 不写 docstr 能自动生成文档?开玩笑
    joesonw
        40
    joesonw  
       2020-11-27 13:12:50 +08:00
    go 自带 ast 包, 随便怎么玩代码生成啊.
    lidashuang
        41
    lidashuang  
       2020-11-27 13:23:20 +08:00
    @meshell 一个很重要的点是 代码和文档同步,fastapi 就做的很好
    DoctorCat
        42
    DoctorCat  
    OP
       2020-11-27 14:07:26 +08:00
    @TransAM 注意审题,FastAPI 自动生成 swager 了解一下?
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   5408 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 30ms · UTC 08:38 · PVG 16:38 · LAX 01:38 · JFK 04:38
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.