干货：利用 Swagger 构建 RESTful API 在线文档-JavaScript中文网-JavaScript教程资源分享门户

什么是 Swagger？

Swagger 是一种使用 OpenAPI 规范构建 API 文档的工具。它允许开发人员描述 API 的行为、参数和输出结果等信息，然后将这些信息格式化成可视化界面的形式，使得 API 的使用者可以直观地了解它的使用方法和行为特征。

Swagger 通过支持多种编程语言和框架，使得开发人员能够轻松地创建和维护 API 文档，并与其他开发人员和 API 的使用者分享和交流。

构建 RESTful API

RESTful API 是目前最常见的 API 设计规范之一，具有易于理解、可扩展性强等特点。接下来，我们将以 Swagger 和 Node.js 框架为例，展示如何使用 Swagger 构建 RESTful API 在线文档。

安装 Swagger

在 Node.js 中，可以使用 npm 包管理工具来安装 Swagger。运行以下命令：

npm install swagger-ui-express swagger-jsdoc

其中，swagger-jsdoc 允许你将 API 文档作为注释集成到代码中，并生成 Swagger 规范格式的 JSON 文件。swagger-ui-express 则使得这个 JSON 文件可以在 web 应用程序中以可视化的形式呈现。

编写 API 文档

创建一个 swagger.js 文件，用于描述 API 文档。以下是一个简单的例子：

// javascriptcn.com 代码示例
const swaggerJsdoc = require('swagger-jsdoc');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
      description: 'API for My Application'
    },
    servers: [
      {
        url: 'http://localhost:3000'
      }
    ],
  },
  apis: ['./routes/*.js'],
};

const specs = swaggerJsdoc(options);

module.exports = specs;

其中，我们定义了 API 的基本信息、服务器地址和 API 注释所在文件的路径。最后，我们通过将这些选项传递给 swaggerJsdoc 函数来生成 Swagger 规范。

在此之后，我们需要在代码中添加 Swagger 注释。例如，以下代码为一个添加联系人的 API 路径添加了 Swagger 注释：

// javascriptcn.com 代码示例
/**
 * @swagger
 * /contacts:
 *   post:
 *     summary: Add a new contact
 *     description: Adds a new contact to the contact list
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/Contact'
 *     responses:
 *       201:
 *         description: Contact created successfully
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/Contact'
 */
router.post('/contacts', (req, res) => {
  // ...
});

在 Swagger 注释中，我们指定了 API 的请求方式、摘要、描述、请求体、响应体结构等信息。

呈现 API 文档

最后，我们需要在应用程序中呈现 Swagger API 文档。在 Express.js 应用程序中，可以通过 swagger-ui-express 包来实现。以下是一个简单的例子：

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

const app = express();
const PORT = 3000;

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

app.listen(PORT, () => {
  console.log(`Server started on http://localhost:${PORT}`);
});

这里我们使用了 /api-docs 路径，让 Swagger API 文档在该路径下呈现。

总结

使用 Swagger 和 Node.js 可以轻松地创建和维护 RESTful API 文档，并与其他开发人员和 API 的使用者分享和交流。通过对 API 的行为、参数和输出结果等信息的描述，我们可以实现 API 的可视化展示，使得 API 的使用更加直观和易于理解。

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