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

Question

我总是习惯使用适当的文档与其他团队共享我的节点端服务。根据此文档，他们将使用我的服务。

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

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

也很奇怪，他们是否像swagger这样支持Node平台的其他库。

谢谢

Answer 1

我有使用快速模块（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 - 这使用旧版本的Swagger，请务必查看Migrating Swagger以升级到最新版本

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

Answer 2

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

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

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

Answer 3

我最近遇到过使用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 4

我使用这样的招摇，因为它在我的快递应用程序上自动提供实时文档：

• API规范：我使用YAML格式的OpenAPI（Swagger）规范记录我的代码。这要归功于swagger-jsdoc。
• 实时文档：swagger-ui-express“将中间件添加到您的快速应用程序中，以提供绑定到您的Swagger文档的Swagger UI。这可以作为您的应用程序中托管的API的活文档。”

然后，只需创建您希望文档存在的路线：

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如何内置对swagger-jsdoc的支持。阅读swagger-ui-express和swagger-jsdocs getting started documentation了解更多信息。

API specification example:

取自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);
});

Generated docs example:

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