使用 OpenAPI 和 Swagger 为 NodeJS 和 Express 提供自动生成文档的 API

嗨，开发者们！

文档和良好的 API 模式非常重要，它以清晰易懂的方式展示了哪些功能可用。

OpenAPI提供了良好的设计模式，而Swagger可以帮助我们使用 OpenAPI 生成文档。

OpenAPI是：

OpenAPI 规范 (OAS) 为 HTTP API 定义了一个标准的、与编程语言无关的接口描述，使得人和计算机无需访问源代码、额外文档或检查网络流量即可发现和理解服务的功能。通过 OpenAPI 正确定义后，使用者只需极少的实现逻辑即可理解远程服务并与之交互。正如接口描述对底层编程的作用一样，OpenAPI 规范消除了调用服务时的猜测。

Swagger 可以帮助我们按照 OpenAPI 的良好标准生成文档。请看以下示例：

我们还可以通过网页上的 Swagger 文档执行路由并获取数据。它使用 curl 从我们的 URL 获取数据。

非常棒的工具！

那么我们来看看如何使用它。在项目根目录下创建 swagger.js 文件：

const swaggerAutogen = require('swagger-autogen')()

const outputFile = './swagger_output.json'
const endpointsFiles = ['./routers/personRouter.js']

swaggerAutogen(outputFile, endpointsFiles)

outputFile包含我们在 Express 上执行的路由的文件配置信息。endpointFiles是需要记录的路由的路径。

当然，之后我们需要安装 swagger-autogen 和 swagger-ui-express。

npm install swagger-autogen and swagger-ui-express

我们需要在 package.json 文件中添加：

  "scripts": {
    "start": "node index.js",
    "swagger-autogen": "node swagger.js"
  },

在文件夹根目录的命令行中，我们可以输入并执行以下命令：

npm run swagger-autogen

然后会生成swagger_output.json文件。我们可以将其添加到 index.js 文件中：

const express = require('express');
const swaggerUi = require('swagger-ui-express')
const swaggerFile = require('./swagger_output.json')
const router = require('./routers/personRouter')

const router = express.Router();
const app = express();

app.use(express.json());
app.use('/person', router.personRouter))
app.use('/doc', swaggerUi.serve, swaggerUi.setup(swaggerFile))

app.listen(3000, () => {
  console.log(`Running on 3000`);
});

我以 personRouter 为例，它包含一些路由。您可以使用任何包含 Express 路由并引用swagger.js的文件。最后，您可以访问：

http://localhost:3000/doc

把它当成游乐场用。

保存这篇文章，我相信你在生活中的一些项目中会需要用到它。如有任何疑问，请在评论区留言。

联系方式
：邮箱：luizcalaca@gmail.com
Instagram：https://www.instagram.com/luizcalaca
LinkedIn：https: //www.linkedin.com/in/luizcalaca/
Twitter： https: //twitter.com/luizcalaca