JavaScript/TypeScript 程序员都是手写 swagger 文档的？
BeautifulSoap · 2022-06-20 18:43:10 +08:00 · 2134 次点击这是一个创建于 872 天前的主题，其中的信息可能已经有所发展或是发生改变。
最近打算用 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
 |
1
moen 2022-06-20 18:55:06 +08:00
|
 |
2
lzgshsj 2022-06-20 19:24:24 +08:00
现在在用 nestjs 框架就是自动生成 swagger ，虽然有一些小瑕疵，不过整体还是很方便
|
 |
3
nomagick 2022-06-20 19:32:56 +08:00
我有，自研的，不开源。
这是一整套东西，输入输出都需要有完整的 typings ，每一级嵌套对象都要有，我的方案是运行时方案，这就需要在运行时也保持全输入输出的 typings, 不排除可以做设计时的，根据 typescript ast 在设计时构造 openapi.json 运行时方案收益更高，可以直接做参数验证。 |
 |
4
lscho 2022-06-20 21:38:18 +08:00 via iPhone
apidoc
|
 |
5
codingBug 2022-06-20 23:05:07 +08:00 via Android
如果只是一些函数参数的话，有 ts 似乎不用专门的文档，有专门的类型声明文件
|
 |
6
XCFOX 2022-06-21 01:09:52 +08:00  1
nestjs 的 swagger 很方便
进一步想想，都用 swagger 了，要不要考虑一下 GraphQL ？ |
 |
7
kinghly 2022-06-21 08:15:17 +08:00 via Android
后端接口生成 swagger ，前端直接拉下来用
|
 |
8
jrtzxh020 2022-06-21 09:00:35 +08:00
就不能写个好好的标题，直接问有什么好用的 JavaScript/TypeScript 生成 swagge 解决方案。这种标题问你们都是 XXX 的？难都回答是的，我们都是手写的，放弃吧？
|
 |
9
BeautifulSoap OP |
|
10
BeautifulSoap OP @nomagick 非常厉害。不过因为我目前还没写具体运行逻辑之类的，所以运行时可能不是最好方法吧。
|
|
11
BeautifulSoap OP @jrtzxh020 可能标题取得不好，见谅。但我是真的好奇啊，我换了数不清的关键字组合，JavaScript swagger 生成 /generate swagger 等等等等，搜出的文章和工具几乎全部都是从 swagger 生成代码。然后还引向 Documentation-Driven Development ，说从 swagger 生成代码是最好的。
所以我就很奇怪难道在 TS/JS 中从代码生成 swagger 是没这种需求的，然后原始 swagger 是手写的吗，实在太强了 不过楼上有人倒是解答了这个问题，swagger 是后端生成交给前端的 |
 |
12
Envov 2022-06-21 15:00:25 +08:00
如果用 node 写点东西，我觉得可以把 types 包装一下导出一个包，前端直接使用 type 会不会比 swagger 好一些？
node 做 server 的生态肯定是不如 java 的 |
 |
13
yetrun 2023-08-07 09:54:30 +08:00
你所问的问题是要基于某个框架，然后问基于这个框架是否提供了 Swagger 文档生成的方案吧。独立地说某个语言提供了 Swagger 文档生成工具是否显得有些抽象呢？后端开发者都是先用框架实现 API 接口，然后根据业务逻辑运行的语义生成 Swagger 文档。
|
|
14
BeautifulSoap OP @yetrun 你有一点完全认识错误了，Swagger 文档生成并不一定和框架绑定。swagger 文档生成完全是可以不依赖框架，直接解析代码中 class 和注释生成文档的。比如 golang 的 swag 工具。这在强类型（尤其静态语言）中是比较常见的。
即便做不到脱离框架，但在强类型语言中，我基本没见过生成 swagger 文档都必须对每个字段都手动标注的情况。而 typescript 就是明明是强类型语言，但我还必须要手动对每个 dto 字段做标注。至于为什么，这是 typescript 本身缺陷导致的结果，这也是为什么 typescript 的项目里装饰器满天飞的原因。 |
|
15
yetrun 2023-08-07 14:46:02 +08:00
@BeautifulSoap 没错，也有可能像你所说的，通过类和注释生成。但是这样只能生成 components 部分，paths 部分还是要和框架对应才行。但你的问题还是要基于你的场景来回答才行，比如你是用什么框架，比如说 koa 框架，然后想要找一个生成 Swagger 文档的方案，如此云云才好答复。
|
|
16
BeautifulSoap OP @yetrun 问题就在 typescript/javascript 连直接从 class 生成 swagger components 的工具都没有。这就是我发这帖最疑惑的地方，很好奇平时用 ts/js 的人到底是怎么写 swagger 的
|
|
17
yetrun 2023-08-07 15:39:01 +08:00
@BeautifulSoap 有没有可能平时用 ts/js 的人不生成 Swagger ？因为主要是以写前端居多，而用 ts 写后端的人大部分是从前端转过去的，需要完成一些小型接口的实现，所以没想到要生成 Swwager 文档。
我观察了一下 koa ，印象中我以前也用过 express ，这两个框架只是一个微型框架，本身没有严格的参数、返回值的语义定义语法，从它们生成 Swagger 很难没有抓手，所以还没有从这两个框架生成 Swagger 文档的方案。 然后一、二楼提到 nest.js ，其提供了 Swagger 文档生成的方案，你可以看一看。 另外，基于语言（通过类和注释）生成 Swagger 文档的，也不是说每种语言都有啊。我自己使用 Ruby 语言做后端，也没有这样的方案，都是基于框架然后生成的。 |
|
18
BeautifulSoap OP @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 语言本身的问题没有更好的解决办法 |
|
19
yetrun 2023-08-07 17:46:54 +08:00
@BeautifulSoap 既然 TS 是强类型的语言，从 class 生成 Swagger 的 Component 是可能的啊。而现实情况没有，说明有这样的需求的人很少。反向倒是有可能，从 Swagger 生成 TypeScript 代码。因为后端很少用 TS 写，有些用 TS 写的是前端开发者，自产自销，要啥文档。
|
|
20
BeautifulSoap OP @yetrun 后端用 TS/JS 的不少，谢谢，express 每周上千万的下载量，nestjs 每周上百万的下载量摆在那里你没法无视。
而且我想你一定是从来都没有用过 TS 吧，TS 中定义的所有类型信息在编译为 JS 后可都会全部丢失哦。TS 无法自动生成 swagger 不是因为用得人少没人做，而是因为从原理上就根本不可能做到。这就是我说的 TS 本身的缺陷/限制。 TS 的这个问题会接连导致其他非常多问题，swagger 生成只是其中质疑，比如你根本没法信任 json 解析出来的对象是符合定义的 class 的，它甚至连最基本的 validation 都做不了。为了给 TS 的这个问题擦屁股，最后结果就是现在 TS 的项目里装饰器满天飞。动不动就出错 |
|
21
yetrun 2023-08-08 11:27:23 +08:00
@BeautifulSoap 那有没有可能，express 做的就是全栈开发，因此也就无所谓生成文档的问题了。nestjs 据一二楼说的是可以生成 Swagger 文档的，但是你说不好用那就这样吧。
我承认一点，TS 编译后类型信息丢失。但转过头一想，语言类型的强弱和生成 Swagger 文档其实没关系。Ruby 是弱类型语言，连类型定义都没有，但是仍然可以生成 Swagger 文档。Java 是强类型语言，但也没有单纯从 Java 类定义生成文档的，必须要借助注解。所以，没有生成 Swagger 的方案，要么是你没找到，要么确实是现在还没有，但和 TS 关系不大。 |
|
22
BeautifulSoap OP @yetrun 服了你了，你一个连 TS 都没怎么用过，不光项目经验都没多少，对包括 java 在内的语言都不了解的人，怎么能做到仿佛什么都懂一样在这高谈阔论。说的话还全是错误
|
|
23
yetrun 2023-08-08 13:20:08 +08:00
@BeautifulSoap 行，你说的都是对的
|
Select Language