Swagger 可以根据现有的快速路由自动生成其 yaml 吗？

Posted 2023-02-16

【中文标题】Swagger 可以根据现有的快速路由自动生成其 yaml 吗？

【英文标题】：Can Swagger autogenerate its yaml based on existing express routes?

【发布时间】：2015-09-26 20:11:03

【问题描述】：

我继承了一个现有的 API，我想大摇大摆地记录它，但我还不知道它的全部范围。 Swagger（或其他中间件/工具）能否根据现有的快速路由自动生成 yaml（用于 swagger）？

对于我在其他问题上看到的情况，这似乎主要是一项手动工作，但我正在仔细检查这里是否有人找到解决此问题的方法。

【问题讨论】：

更新：我最终使用了swagger-ui，并简单地用端点手动填充了 json 文档。一旦你弄清楚它是如何工作的，它就像使用邮递员一样简单，但它可以供第三方使用，而无需与你的代码进行交互。

【参考方案1】：

我在自动生成 Swagger json 和为我帮助构建的 API 手动编写它方面都有经验。根据我的经验，这是两者的优缺点。

Swagger 自动文档生成：

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

优点

超级容易记录。只需在资源定义上方添加几行代码，模块就会自动生成文档（json）。

缺点

当您使用此软件包时，您不再直接使用 Express。您的路线定义必须通过 Swagger 模块定义，这会让您远离 vanilla Express。

Swagger 手册文档生成：

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

优点

这种方法将文档与 Express 框架分离。 Express 端点的编写方式与它们通常的编写方式相同，并且 Swagger 文档的定义与 Express 框架分开。让你写纯快递。

缺点

由于您自己手动编写和更改 yaml 或 json，文档更改变得有点乏味。这比仅更新资源上方的几行代码要困难一些。这种方法也更容易出现文档拼写错误和错误，因为它完全是手动输入的。

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

结论

对于这个 API 项目，我们首先使用 swagger-node-express 包自动生成文档。但是，我们意识到将 swagger 文档与 express 库分离对于使我们能够使用 Express 的所有特性和功能非常重要。我建议手动编写文档以完全控制您的应用将使用的 Swagger 文档和 Express Web 框架。

【讨论】：

谢谢 Mike，我理解这些方法，但我认为第一个方法并不是真正的“自动魔术”，因为我仍然需要定义大多数情况。我正在寻找基本上可以解释路线并生成类似手动文档的东西，我可以填写它无法从代码本身解释的空白。

搜索了两天，但我还没有找到端到端的工作解决方案。 npmjs.com/package/expressjs-api-explorer 看起来很有前途，但有问题，对我不起作用。想法是使用 API-Explorer 库生成输出并转换为 swagger 所期望的 YAML，然后使用 Mike 建议的可处理静态 YAML 文件的众多库之一。

你找到解决这个问题的好方法了吗？我尝试使用Swagger-Node-Express-For-Existing-APIs，但没有成功。

我们采用手动方式。这并没有那么悲惨，在 2-3 天后，我们获得了超过 300 个端点的完整文档。

@Mike - 手动方法的问题在于您将文档从代码中移开。根据我的经验，这几乎不可避免地会在某些时候导致文档过时（这可能比没有文档更糟糕），因为现在您必须在单独的地方维护文档。保持文档最新的最佳方法是使其尽可能接近代码。归根结底，代码才是生存之道，因此，无论我们必须保留什么重要的工件，如果它们被固定在代码上，它们就有最大的生存机会。

【参考方案2】：

是的！！！。你可以使用这个很棒的项目typescript-test。这是sample app。克隆它，运行 npm i,npm run swagger 并转到 /dist/swagger.json。完毕。 Swagger yaml 和 json 基于 express 路由生成！

【讨论】：

我无法再访问那个 repo（我们当时走的是手动路线）。但我很想有机会对此进行测试。它使用什么探索方法？

我看到它需要打字稿，它依赖于注释来“猜测”路线。我不认为它对那个有用。

【参考方案3】：

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

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

【讨论】：

你能添加 sn-ps 的代码来演示 OP 将如何处理这个问题吗？

抱歉没有问到你的问题。如果您要询问 express-oas-generator 模块，那么您唯一需要的是 . expressOasGenerator.init(app, );如果您询问实施细节，那么这里是主要的初始化例程：github.com/mpashkovskiy/express-oas-generator/blob/master/…

他不觉得这回答了我的问题......我也没有。这是一个 hack，但不是解决方案。我等不及其他人使用我的端点来知道它们是什么。他们中的许多人有可能直到为时已晚才被发现。

你是对的，它是一个黑客。有两种选择：要么自己编写规范文件，要么使用 hack 并部分记录所有端点。

@mpashkovskiy - 不确定你是否做任何 C# 工作，但有一个名为 Swashbuckle 的 nuget 库，它可以在不需要你实际运行请求的情况下生成 swagger 文档。它甚至会在每个方法之上使用您的 XML cmets 来记录其余的操作和参数。不过，这可能很难用 javascript 来完成。

【参考方案4】：

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

文档坚持代码，也让快递代码保持纯净。

指南：

https://dev.to/acanimal/express-api-with-autogenerated-openapi-doc-through-swagger-7na

https://dev.to/akshendra/generating-documentation-on-the-fly-in-express-2652

【参考方案5】：

使用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 实例和挂载的路由。

专业人士您无需执行提前请求即可获取可用路线的更新列表。

CONs它提供了无类型参数功能。