如何将 swagger 与我的 express 应用程序集成

Question

我过去常常通过适当的文档将我的节点端服务分享给其他一些团队。根据这份文档，他们将使用我的服务。

关于这个，当我和其他人交谈时。他建议我使用 swagger。但是我不知道如何集成到我的应用程序中。

我的申请是用Express写的。我已经在 google 中搜索过这个，我没有找到任何好的教程。如果有人已经实施，你能建议我吗？哪个模块好，怎么样。

也很想知道，它们是否有其他像 swagger 这样支持 Node 平台的库。

谢谢

Answer 1

我不太清楚你的要求，但我认为你正在寻找这样的东西：swagger-tools

我用过这个模块，感觉很棒。它公开了一些中间件，您可以将其绑定到您创建的 Express app。例如，如果您记录了您的服务并且该文档是 Swagger compliant，那么您可以将该文档传递给中间件。中间件做了一些很棒的事情，比如根据文档中的定义连接请求处理程序，并根据文档中的定义验证请求。

它有一个很棒的 tutorial 并且非常容易设置。我希望这对您有所帮助，并且符合您的要求。

Answer 2

我有使用 express 模块 (swagger-node-express) 记录 Express API 的经验。我也有使用手动 Swagger JSON 文档记录 Express API 的经验。

我建议不要将自己束缚于 Swagger 文档的模块。大多数模块（尤其是 swagger-node-express）迫使您以不同的方式编写 Express 代码来处理文档。当使用 JSON 手动编写 Swagger 文档时，您可以编写 Express 并将文档与路由分离。

使用 Swagger UI 设置文档样式并将其添加到网页中。

以下是您在开始时可以使用的一些资源：

Swagger Editor - 编辑您的 swagger 文档并实时查看您的更改
Swagger Docs - JSON
的 Swagger 规范 Tutorial - This uses an older version of Swagger, be sure to check out Migrating Swagger升级到最新版本

另外，看看这个解释手动和基于模块的 swagger 文档生成之间的区别的答案 -> HERE。

Answer 3

我这样使用 swagger，因为它会在我的 Express 应用程序上自动为我提供实时文档：

API 规范： 我使用 YAML 格式的 OpenAPI (Swagger) 规范记录我的代码。这要归功于 swagger-jsdoc.
实时文档： swagger-ui-express "adds middleware to your express app to serve the Swagger UI bound to your Swagger document. This acts as living documentation for your API hosted from within your app."

那么只需创建您希望文档所在的路径即可：

const swaggerSpec = swaggerJSDoc({
  swaggerDefinition: {
    info: {
      title: 'My App API',
      version: '1.0.0'
    }
  },
  apis: ['./routes/index.js']
});

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

看看如何 swagger-ui-express han built-in 支持 swagger-jsdoc.阅读 swagger-ui-express 和 swagger-jsdocs getting started documentation 了解更多信息。

API 规格示例：

取自 swagger-jsdocs getting started documentation.

/**
 * @swagger
 * /login:
 *   post:
 *     description: Login to the application
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: username
 *         description: Username to use for login.
 *         in: formData
 *         required: true
 *         type: string
 *       - name: password
 *         description: User's password.
 *         in: formData
 *         required: true
 *         type: string
 *     responses:
 *       200:
 *         description: login
 */
app.post('/login', function(req, res) {
  res.json(req.body);
});

生成的文档示例：

它们看起来几乎像 Swagger UI example。

Answer 4

我最近发现使用 swagger 实现 API 文档。我已经使用 "swagger-ui-express" npm 模块来实现它。在运行时创建 JSON，即服务器启动后运行，我捕获数据并根据如下文件中的 swagger 规范进行修改。

https://editor.swagger.io/这里可以看到JSON中的swagger规范。

需要 "swagger-ui-express" 模块，创建一个 JSON 并将文件提供给 swaggerui，如下所示。

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

Answer 5

我想你正在寻找这个：

用于 ExpressJS 应用程序的 OpenAPI (Swagger) 规范生成器

https://github.com/mpashkovskiy/express-oas-generator

要使其正常工作，您需要执行以下操作：

1) 安装库：npm i express-oas-generator —save

2) 与 ExpressJS 集成：

const express = require('express')
const expressOasGenerator = require('express-oas-generator')

expressOasGenerator.init(app, {});

3) 打开以下 URL：http://localhost:3000/api-docs（将 localhost:3000 替换为您的主机名）

它将直接从注册的路由生成一个非常好的 Swagger 输出：

如何将 swagger 与我的 express 应用程序集成

how to integrate swagger with my express application

node.js

express

swagger

swagger-ui

API 规格示例：

生成的文档示例：