如何在 Express.js 中集成 Swagger API 文档-JavaScript中文网-JavaScript教程资源分享门户

如何在 Express.js 中集成 Swagger API 文档

Swagger API 文档是一种常用的文档编写工具，它可以快速地生成 API 说明文档，方便使用者阅读和理解接口的功能。在 Express.js 中，集成 Swagger API 文档非常方便，只需要简单的几步操作即可完成。本文将介绍如何在 Express.js 中集成 Swagger API 文档，并提供示例代码。

步骤一：安装 Swagger UI 和 Swagger JSDoc

在 Express.js 中集成 Swagger API 文档，首先需要安装 Swagger UI 和 Swagger JSDoc。Swagger UI 是一个漂亮的文档页面，它能够快速的展示接口文档。Swagger JSDoc 则是一个将 JSDoc 标记与 Swagger 规范集成的工具，它能够将注释转换为 Swagger 的 API 文档。

通过以下命令来安装 Swagger UI 和 Swagger JSDoc：

npm i swagger-ui-express swagger-jsdoc -S

步骤二：配置 Swagger JSDoc

在你的项目根目录下新建一个 jsdoc.json 文件，用于配置 Swagger JSDoc。下面是一个简单的示例配置文件：

// javascriptcn.com 代码示例
{
  "swaggerDefinition": {
    "info": {
      "title": "API",
      "version": "1.0.0",
      "description": "API description"
    },
    "host": "localhost:3000",
    "basePath": "/api",
    "produces": [
      "application/json"
    ],
    "consumes": [
      "application/json"
    ],
    "schemes": [
      "http"
    ]
  },
  "apis": ["**/*.js"]
}

其中，swaggerDefinition 中包含了一些基础信息，比如文档的标题、版本号、接口描述等。apis 属性则是指定了需要生成文档的源代码目录。

步骤三：配置 Express.js

在 Express.js 中使用 Swagger API 文档也非常简单，只需要在你的项目中引入上面安装的模块，并在 app.js 中添加以下代码即可：

const swaggerUi = require('swagger-ui-express');
const swaggerJSDoc = require('swagger-jsdoc');

const options = require('./jsdoc.json');
const swaggerSpec = swaggerJSDoc(options);

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

其中，options 是指定了 Swagger JSDoc 的配置文件，swaggerSpec 则是通过 swaggerJSDoc 生成的 Swagger 规范。

最后，启动项目，访问 http://localhost:3000/api-docs，你就能够看到生成的文档页面了。

示例代码

你可以复制以下代码来快速体验如何在 Express.js 中集成 Swagger API 文档：

// javascriptcn.com 代码示例
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerJSDoc = require('swagger-jsdoc');

const app = express();

const options = {
  swaggerDefinition: {
    info: {
      title: 'API',
      version: '1.0.0',
      description: 'API description'
    },
    host: 'localhost:3000',
    basePath: '/api',
    produces: ['application/json'],
    consumes: ['application/json'],
    schemes: ['http']
  },
  apis: ['**/*.js']
};

const swaggerSpec = swaggerJSDoc(options);

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

app.get('/hello', (req, res) => {
  /**
   * @swagger
   * /hello:
   *   get:
   *     description: Returns the hello world message
   *     produces:
   *       - application/json
   *     responses:
   *       200:
   *         description: Hello world message
   */
  res.send('Hello World!');
});

app.listen(3000, () => {
  console.log('Example app listening on port 3000!');
});

总结

在本文中，我们介绍了如何在 Express.js 中集成 Swagger API 文档。通过学习本文，你了解了如何安装和集成 Swagger UI 和 Swagger JSDoc，并获得了一个可以快速体验的示例代码。如有疑问或需要更详细的指导，请参考 Swagger 官方文档。

来源：JavaScript中文网，转载请注明来源本文地址：https://www.javascriptcn.com/post/653fb4957d4982a6eb944591