Express.js 中使用 SwaggerUI 生成 API 文档

在现代的 Web 开发中，API 文档是非常重要的一部分。它可以帮助前后端开发人员更好地理解和使用 API 接口，提高开发效率和代码质量。Swagger 是一个流行的 API 文档工具，它可以帮助我们快速生成和管理 API 文档。在本文中，我们将介绍如何在 Express.js 中使用 SwaggerUI 生成 API 文档。

安装 SwaggerUI

首先，我们需要安装 SwaggerUI。可以通过 npm 命令进行安装：

npm install swagger-ui-express

配置 SwaggerUI

在 Express.js 中使用 SwaggerUI 需要进行以下配置：

1. 引入 SwaggerUI：

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

1. 引入 Swagger 文档：

const swaggerDocument = require('./swagger.json');

这里的 swagger.json 是我们自己编写的 Swagger 文档，可以使用 Swagger Editor 来编写。

1. 配置 SwaggerUI：

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

这里的 /api-docs 是我们访问 SwaggerUI 的路径，可以根据自己的需要进行修改。

编写 Swagger 文档

接下来，我们需要编写 Swagger 文档。Swagger 文档使用 YAML 或 JSON 格式编写，这里我们使用 JSON 格式。

下面是一个简单的 Swagger 文档示例：

// www.javascriptcn.com code example
{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "My API",
    "description": "API 文档"
  },
  "host": "localhost:3000",
  "basePath": "/api",
  "tags": [
    {
      "name": "users",
      "description": "用户管理"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "tags": [
          "users"
        ],
        "summary": "获取用户列表",
        "responses": {
          "200": {
            "description": "成功",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/User"
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "users"
        ],
        "summary": "创建用户",
        "parameters": [
          {
            "name": "user",
            "in": "body",
            "description": "用户信息",
            "required": true,
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "User": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "description": "用户 ID"
        },
        "name": {
          "type": "string",
          "description": "用户名"
        },
        "email": {
          "type": "string",
          "description": "用户邮箱"
        }
      }
    }
  }
}

这个示例中定义了一个 /users 的 API 接口，其中包含了获取用户列表和创建用户两个操作。同时，还定义了一个 User 对象，用于描述用户信息。

访问 SwaggerUI

启动 Express.js 服务器后，我们可以通过访问 http://localhost:3000/api-docs 来查看 SwaggerUI 生成的 API 文档。在 SwaggerUI 中，我们可以通过点击左侧的菜单栏来查看不同的 API 接口，同时还可以查看接口的请求参数、响应结果等信息。

结语

本文介绍了在 Express.js 中使用 SwaggerUI 生成 API 文档的方法，同时还提供了 Swagger 文档的编写示例。通过使用 SwaggerUI，我们可以更好地管理和使用 API 接口，提高开发效率和代码质量。

来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/67d50747a941bf7134954e0b