V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
V2EX 提问指南
BeautifulSoap
V2EX  ›  问与答

JavaScript/TypeScript 程序员都是手写 swagger 文档的?

  •  
  •   BeautifulSoap · 55 天前 · 1250 次点击
    这是一个创建于 55 天前的主题,其中的信息可能已经有所发展或是发生改变。

    最近打算用 node 写点东西,就遇到了写接口文档的问题。之前用 Python, Go, Kotlin 等语言都有很方便的 swagger 生成工具,直接就可以根据代码里的类结构自动生成 swagger 文档

    但是 node 这边似乎没有这方面的工具?就连 TypeScript 这种强类型的语言,我找了一大圈也没找到活跃度高用得人比较多的类似工具。

    找了一圈全都是从 swagger 生成 js/ts 代码的工具。难道 JS/TS 程序员都是先手写 swagger 文档然后再反向生成的代码的?实在太强了,手写 swagger 因为过于痛苦我根本难以想象。。。。

    至于找到的少数工具,基本都是不活跃或用的人少。至于 swagger-jsdoc 这样的工具,实际上就是直接把 swagger 文档给硬塞到注释里,实在没法称为自动生成。。。

    所以想问一下有没有类似的其他语言中的 swagger 自动生成工具,可以直接根据我定义好的 TypeScript class 或 interface 还有路由直接生成 swagger 定义文件?

    12 条回复    2022-06-21 15:00:25 +08:00
    moen
        1
    moen  
       55 天前
    lzgshsj
        2
    lzgshsj  
       55 天前
    现在在用 nestjs 框架就是自动生成 swagger ,虽然有一些小瑕疵,不过整体还是很方便
    nomagick
        3
    nomagick  
       55 天前
    我有,自研的,不开源。

    这是一整套东西,输入输出都需要有完整的 typings ,每一级嵌套对象都要有,我的方案是运行时方案,这就需要在运行时也保持全输入输出的 typings, 不排除可以做设计时的,根据 typescript ast 在设计时构造 openapi.json

    运行时方案收益更高,可以直接做参数验证。
    lscho
        4
    lscho  
       55 天前 via iPhone
    apidoc
    codingBug
        5
    codingBug  
       55 天前 via Android
    如果只是一些函数参数的话,有 ts 似乎不用专门的文档,有专门的类型声明文件
    XCFOX
        6
    XCFOX  
       55 天前   ❤️ 1
    nestjs 的 swagger 很方便
    进一步想想,都用 swagger 了,要不要考虑一下 GraphQL ?
    kinghly
        7
    kinghly  
       54 天前 via Android
    后端接口生成 swagger ,前端直接拉下来用
    jrtzxh020
        8
    jrtzxh020  
       54 天前
    就不能写个好好的标题,直接问有什么好用的 JavaScript/TypeScript 生成 swagge 解决方案。这种标题问你们都是 XXX 的?难都回答是的,我们都是手写的,放弃吧?
    BeautifulSoap
        9
    BeautifulSoap  
    OP
       54 天前 via Android
    @moen
    @lzgshsj

    多谢,没想到在网络框架里找。本来以为写个 swagger 引入个框架太重了,但发现 @nestjs/swagger 这个包可以单独使用,轻便多了,目前用得挺不错的
    BeautifulSoap
        10
    BeautifulSoap  
    OP
       54 天前 via Android
    @nomagick 非常厉害。不过因为我目前还没写具体运行逻辑之类的,所以运行时可能不是最好方法吧。
    BeautifulSoap
        11
    BeautifulSoap  
    OP
       54 天前 via Android
    @jrtzxh020 可能标题取得不好,见谅。但我是真的好奇啊,我换了数不清的关键字组合,JavaScript swagger 生成 /generate swagger 等等等等,搜出的文章和工具几乎全部都是从 swagger 生成代码。然后还引向 Documentation-Driven Development ,说从 swagger 生成代码是最好的。
    所以我就很奇怪难道在 TS/JS 中从代码生成 swagger 是没这种需求的,然后原始 swagger 是手写的吗,实在太强了

    不过楼上有人倒是解答了这个问题,swagger 是后端生成交给前端的
    Envov
        12
    Envov  
       54 天前
    如果用 node 写点东西,我觉得可以把 types 包装一下导出一个包,前端直接使用 type 会不会比 swagger 好一些?
    node 做 server 的生态肯定是不如 java 的
    关于   ·   帮助文档   ·   API   ·   FAQ   ·   我们的愿景   ·   广告投放   ·   感谢   ·   实用小工具   ·   1078 人在线   最高记录 5497   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 52ms · UTC 19:46 · PVG 03:46 · LAX 12:46 · JFK 15:46
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.