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

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

  •  
  •   BeautifulSoap · 2022-06-20 18:43:10 +08:00 · 1856 次点击
    这是一个创建于 648 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

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

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

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

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

    23 条回复    2023-08-08 13:20:08 +08:00
    moen
        1
    moen  
       2022-06-20 18:55:06 +08:00
    lzgshsj
        2
    lzgshsj  
       2022-06-20 19:24:24 +08:00
    现在在用 nestjs 框架就是自动生成 swagger ,虽然有一些小瑕疵,不过整体还是很方便
    nomagick
        3
    nomagick  
       2022-06-20 19:32:56 +08:00
    我有,自研的,不开源。

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

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

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

    不过楼上有人倒是解答了这个问题,swagger 是后端生成交给前端的
    Envov
        12
    Envov  
       2022-06-21 15:00:25 +08:00
    如果用 node 写点东西,我觉得可以把 types 包装一下导出一个包,前端直接使用 type 会不会比 swagger 好一些?
    node 做 server 的生态肯定是不如 java 的
    yetrun
        13
    yetrun  
       235 天前
    你所问的问题是要基于某个框架,然后问基于这个框架是否提供了 Swagger 文档生成的方案吧。独立地说某个语言提供了 Swagger 文档生成工具是否显得有些抽象呢?后端开发者都是先用框架实现 API 接口,然后根据业务逻辑运行的语义生成 Swagger 文档。
    BeautifulSoap
        14
    BeautifulSoap  
    OP
       235 天前
    @yetrun 你有一点完全认识错误了,Swagger 文档生成并不一定和框架绑定。swagger 文档生成完全是可以不依赖框架,直接解析代码中 class 和注释生成文档的。比如 golang 的 swag 工具。这在强类型(尤其静态语言)中是比较常见的。
    即便做不到脱离框架,但在强类型语言中,我基本没见过生成 swagger 文档都必须对每个字段都手动标注的情况。而 typescript 就是明明是强类型语言,但我还必须要手动对每个 dto 字段做标注。至于为什么,这是 typescript 本身缺陷导致的结果,这也是为什么 typescript 的项目里装饰器满天飞的原因。
    yetrun
        15
    yetrun  
       235 天前
    @BeautifulSoap 没错,也有可能像你所说的,通过类和注释生成。但是这样只能生成 components 部分,paths 部分还是要和框架对应才行。但你的问题还是要基于你的场景来回答才行,比如你是用什么框架,比如说 koa 框架,然后想要找一个生成 Swagger 文档的方案,如此云云才好答复。
    BeautifulSoap
        16
    BeautifulSoap  
    OP
       235 天前
    @yetrun 问题就在 typescript/javascript 连直接从 class 生成 swagger components 的工具都没有。这就是我发这帖最疑惑的地方,很好奇平时用 ts/js 的人到底是怎么写 swagger 的
    yetrun
        17
    yetrun  
       235 天前
    @BeautifulSoap 有没有可能平时用 ts/js 的人不生成 Swagger ?因为主要是以写前端居多,而用 ts 写后端的人大部分是从前端转过去的,需要完成一些小型接口的实现,所以没想到要生成 Swwager 文档。

    我观察了一下 koa ,印象中我以前也用过 express ,这两个框架只是一个微型框架,本身没有严格的参数、返回值的语义定义语法,从它们生成 Swagger 很难没有抓手,所以还没有从这两个框架生成 Swagger 文档的方案。

    然后一、二楼提到 nest.js ,其提供了 Swagger 文档生成的方案,你可以看一看。

    另外,基于语言(通过类和注释)生成 Swagger 文档的,也不是说每种语言都有啊。我自己使用 Ruby 语言做后端,也没有这样的方案,都是基于框架然后生成的。
    BeautifulSoap
        18
    BeautifulSoap  
    OP
       235 天前
    @yetrun 你应该看一下我这帖是服么时候发的。

    还有你说:“因为主要是以写前端居多,而用 ts 写后端的人大部分是从前端转过去的,需要完成一些小型接口的实现,所以没想到要生成 Swwager 文档” 既然你都这么说了,那么自然我这贴的疑问就很正常了 : “找了一圈全都是从 swagger 生成 js/ts 代码的工具。难道 JS/TS 程序员都是先手写 swagger 文档然后再反向生成的代码的?实在太强了,手写 swagger 因为过于痛苦我根本难以想象”。
    所以我很敬佩你口中的 js/ts 程序员,一个个都是工作中手写 swagger 或者根本不写 swagger 的强者

    以及,关于 nestjs ,你看了我这帖的发帖时间的话,就应该注意到这是一年前的坟帖。这一年时间我早就体会到了再 ts 上 swagger 生成到底是个什么鬼体验了。
    我上面已经跟你说过两次了,因为 ts 语言本身的缺陷/限制,它明明就是一个强类型语言,但却根本就不存在自动解析 class 生成 swagger 文档的可能性。nestejs 里所谓的 swagger 文档生成实际上就是漫天飞舞写装饰器。手动的一个个把 swagger 的各个元素通过装装饰器给写出来,本质上和直接在注释里写 swagger 的 yaml 文件没多大区别,而且极其容易出错(实际项目开发中已经出错 N 次了)。所以问 ts 下有没有更好的解决办法,答案就是没有,这是 ts 语言本身的问题没有更好的解决办法
    yetrun
        19
    yetrun  
       235 天前
    @BeautifulSoap 既然 TS 是强类型的语言,从 class 生成 Swagger 的 Component 是可能的啊。而现实情况没有,说明有这样的需求的人很少。反向倒是有可能,从 Swagger 生成 TypeScript 代码。因为后端很少用 TS 写,有些用 TS 写的是前端开发者,自产自销,要啥文档。
    BeautifulSoap
        20
    BeautifulSoap  
    OP
       235 天前
    @yetrun 后端用 TS/JS 的不少,谢谢,express 每周上千万的下载量,nestjs 每周上百万的下载量摆在那里你没法无视。
    而且我想你一定是从来都没有用过 TS 吧,TS 中定义的所有类型信息在编译为 JS 后可都会全部丢失哦。TS 无法自动生成 swagger 不是因为用得人少没人做,而是因为从原理上就根本不可能做到。这就是我说的 TS 本身的缺陷/限制。

    TS 的这个问题会接连导致其他非常多问题,swagger 生成只是其中质疑,比如你根本没法信任 json 解析出来的对象是符合定义的 class 的,它甚至连最基本的 validation 都做不了。为了给 TS 的这个问题擦屁股,最后结果就是现在 TS 的项目里装饰器满天飞。动不动就出错
    yetrun
        21
    yetrun  
       234 天前
    @BeautifulSoap 那有没有可能,express 做的就是全栈开发,因此也就无所谓生成文档的问题了。nestjs 据一二楼说的是可以生成 Swagger 文档的,但是你说不好用那就这样吧。

    我承认一点,TS 编译后类型信息丢失。但转过头一想,语言类型的强弱和生成 Swagger 文档其实没关系。Ruby 是弱类型语言,连类型定义都没有,但是仍然可以生成 Swagger 文档。Java 是强类型语言,但也没有单纯从 Java 类定义生成文档的,必须要借助注解。所以,没有生成 Swagger 的方案,要么是你没找到,要么确实是现在还没有,但和 TS 关系不大。
    BeautifulSoap
        22
    BeautifulSoap  
    OP
       234 天前
    @yetrun 服了你了,你一个连 TS 都没怎么用过,不光项目经验都没多少,对包括 java 在内的语言都不了解的人,怎么能做到仿佛什么都懂一样在这高谈阔论。说的话还全是错误
    yetrun
        23
    yetrun  
       234 天前
    @BeautifulSoap 行,你说的都是对的
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   2877 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 27ms · UTC 11:32 · PVG 19:32 · LAX 04:32 · JFK 07:32
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.