Swagger是否可以根据现有的express路由自动生成其yaml文件？

Question

Swagger是否可以根据现有的express路由自动生成其yaml文件？

node.jsrestexpressdocumentationswagger

61

我继承了一个现有的API，并希望使用Swagger对其进行文档化，但我还不完全了解其全部范围。 Swagger（或其他中间件/工具）是否可以根据现有的express路由自动生成yaml（用于swagger）？

从其他问题中看到的情况，似乎这主要是手动工作，但我正在仔细检查是否有人找到了解决方法。

- Manatax

更新：我最终使用了 swagger-ui ，并且手动填充了端点的 json 文档。一旦你弄清楚了它的工作原理，它就像使用 postman 一样简单，但是它可以让第三方更方便地与你的代码交互。 - Manatax

7个回答

7

有一个选项：您可以嵌入中间件，分析所有请求和响应，并为您生成规范：https://github.com/mpashkovskiy/express-oas-generator

然后，您可以通过您的应用程序Swagger UI使用它，例如：http://host:port/api-docs

- mpashkovskiy

你能添加一些代码片段来演示原帖作者如何进行操作吗？ - Marcello B.

抱歉，我没有理解你的问题。如果你在询问express-oas-generator模块，那么你唯一需要的就是：expressOasGenerator.init(app, {});如果你想了解实现细节，那么这里是主要的初始化程序：https://github.com/mpashkovskiy/express-oas-generator/blob/master/index.js#L291 - mpashkovskiy

他觉得这并没有回答我的问题...而我也是这样认为的。这只是一个hack，而不是解决方案。我不能等待别人使用我的端点来了解它们。有很多潜在的问题可能直到太晚才被发现。 - Manatax

你是对的，这确实是个黑科技。有两个选择：要么自己编写规范文件，要么使用这个黑科技并部分记录所有端点。 - mpashkovskiy

@mpashkovskiy - 不确定您是否从事C#工作，但有一个名为Swashbuckle的NuGet库可以生成Swagger文档，而无需实际运行请求。它甚至会使用每个方法上方的XML注释来记录REST操作和参数。不过，使用JavaScript可能会比较困难。 - dcp

@dcp，谢谢指出来，我确实这么做了 - 我会试一下的。在强类型语言中，你可以分析方法的参数和返回值，并构建相应的模式，这是一个事实。 - mpashkovskiy

3

使用 express-sitemap-html，您可以自动地生成一个精简版的 Open API 定义（仅包括路由参数），并为现有的 express 应用程序的所有路由安装 Swagger UI。您只需要：

const sitemap = require('express-sitemap-html')
...
sitemap.swagger('Your app name', app) // given that app is an express instance

不必在运行时分析HTTP请求，此方法检查express app实例和已挂载的路由。

优点：您无需执行先前的请求即可获取可用路由的更新列表。

缺点：它提供了未经过类型定义的参数功能。

- Miguel Gamboa

3

是的!!! 你可以使用这个很棒的项目 typescript-test。这里有一个示例应用程序。克隆它，运行npm i，npm run swagger并转到/dist/swagger.json。完成了。Swagger yaml和json是基于express路由生成的！

- Dariusz Filipiak

1

我不再有访问那个仓库的权限了（当时我们采用了手动方式）。但我很想有机会测试一下。它使用哪种探索方法？ - Manatax

我看到它需要TypeScript，并且依赖于注释来“猜测”路由。我不认为它适用于那个。 - Manatax

0

看一下swagger-jsdoc。这是一种不同的方法。

文档紧贴代码，同时也让express代码保持纯净。

指南：

- ovidiu-miu

0

你可以使用swagger-autogen，这是一款允许你通过注释自定义类型的工具。缺点是你需要花时间学习如何添加文档。

- kato2

0

我为自己写了express-openapi-gen来解决这个问题。它目前还处于预发布阶段，所以不能保证它能支持你所需的一切，但我欢迎贡献。

app.get("/banana/:count",
    // use JSDoc for JS
    (req: express.Request<{ count: string }, string>, res) => {
        res.send([...Array(Number(req.params.count))].map(_ => "").join(''));
    });

与上述示例（经过我尝试的那些）不同的是，

此包不依赖于注释来生成文档。
- 如果没有类型，它仍将识别和映射所有路由，识别路由参数并为接受它们的HTTP方法提供松散类型的请求体。如果选择使用类型（或使用JSDoc进行注释），可以使用来自于 @types/express 和 @types/express-serve-static-core 的接口，这些可能已经在您使用中。
它在运行时从源代码构建文档，而不是通过分析请求之后的情况

（我意识到这是一个古老的帖子，但我多次访问此问题以寻找答案，所以我想分享我的解决方案。）

我写了这个来尝试在Express中重新创建Swashbuckle.AspNetCore，但由于在JSDoc / TypeScript中对强类型推断的困扰，它仍然非常不完整。我正在研究ts-pattern，但我可能会努力说服我的团队改用C# minimal APIs。

- aes

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Mike · Accepted Answer

我既有自动生成Swagger json的经验，也有手动编写API Swagger文档的经验。基于我的经验，以下是两种方法的利弊。

Swagger 自动文档生成:

我们使用swagger-node-express模块结合swagger-ui使用。 https://www.npmjs.com/package/swagger-node-express
https://github.com/swagger-api/swagger-ui

优点：

非常容易文档化，只需要在资源定义之前加入几行代码即可，模块会自动生成文档(json)。

缺点：

使用此包时，您不再使用纯Express。您的路由定义必须通过Swagger模块定义，这使您远离了原生Express。

Swagger 手动文档生成:

我们将swagger-ui引入项目中，并手动编写文档。
https://github.com/swagger-api/swagger-ui

优点：

该方法将文档与Express框架分离。Express端点按照正常方式编写，Swagger文档则与Express框架分开定义。允许您编写纯粹的Express。

缺点：

由于您需要手动编写和更改yaml或json文件，因此文档更改会变得有点繁琐。这比仅更新资源前的几行代码要困难一些。这种方法也更容易出现文档错别字和错误，因为它完全是手工输入的。

如果您打算手动编写Swagger文档，请使用下面的Swagger编辑器验证您的手动文档。
http://editor.swagger.io/#/

结论

对于这个API项目，我们开始使用swagger-node-express包自动生成文档。但是，我们意识到将Swagger文档与express库解耦是很重要的，以便我们可以使用Express的所有功能和功能。我建议手动编写文档，以便完全控制Swagger文档和应用程序将使用的Express Web框架。