如何将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 Docs - JSON的Swagger规范 Tutorial - 这使用较早版本的Swagger，请务必查看Migrating Swagger以升级到最新版本

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

Answer 2

我不清楚你的要求是什么，但我认为你正在寻找这样的事情：swagger-tools

我使用这个模块，它很棒。它公开了一些可以绑定到您创建的Express source: function( term, callback ) { movies.search( term ).done( function() { callback( movies.toJSON() ); } ); }, 的中间件。例如，如果您记录了您的服务并且文档是Swagger compliant，那么您可以将该文档传递给中间件。中间件做了一些很棒的事情，比如根据文档中的定义连接请求处理程序，并根据文档中的定义验证请求。

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

Answer 3

我最近遇到了使用swagger实现API文档的情况。我已经使用“ swagger-ui-express” npm模块来实现它。 在运行时创建JSON，即，一旦服务器开始运行，我就捕获了数据并根据以下文件的详细规范进行了修改。

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

需要“ 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 ＆＃34;为您的快递应用添加中间件，以便为Swagger文档提供绑定的Swagger UI。这可以作为您的应用内托管的API的实时文档。＆＃34;

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

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规范示例：

取自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 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输出：