Swagger入门：轻松搭建API文档

本文详细介绍了Swagger入门的相关内容，包括Swagger的定义、作用、安装与配置、创建API文档以及使用Swagger UI查看文档的方法。通过这些步骤，你可以轻松搭建高质量的API文档，并提高API的开发和维护效率。从安装到生成交互式文档，Swagger入门涵盖全过程，帮助开发者快速上手。

Swagger是一种用于描述、生成、调用和可视化RESTful风格Web服务的框架。它提供了一个强大的工具集合，帮助开发者快速搭建高质量的API文档，并使API的测试和调试更为简便。Swagger的核心优势在于它能够提供一个统一的标准来定义、描述API，以及生成交互式的API文档，这使得API的开发和使用更加高效。

Swagger的定义和作用

Swagger定义了一套描述API的标准，称为Swagger规范。Swagger规范使用了一种称为OpenAPI规范的语言来描述API的各个部分，包括资源、资源的操作、请求和响应的格式等。这一规范使得Swagger能够生成交互式的API文档，并在文档中展示API的使用方法、参数、返回值等信息。此外，Swagger还提供了多种工具，用于生成API文档、测试API、可视化API等，极大地提高了API开发、测试和维护的效率。

Swagger的主要作用包括：

• 描述API：通过定义一套标准，Swagger能够详细描述API的各个方面，如资源、请求和响应的格式、参数等。
• 生成文档：基于Swagger规范，可以自动生成交互式的API文档，供开发者参考和使用。
• 调试API：Swagger提供了测试API的功能，允许用户直接在文档中测试API，从而快速发现并解决问题。
• 可视化API：Swagger可以生成交互式的API文档，使得API的结构和操作一目了然，便于理解和使用。
• 版本管理：通过Swagger，可以轻松管理不同版本的API，确保兼容性和稳定性。
• 社区支持：Swagger拥有活跃的社区，提供了丰富的资源和工具，帮助开发者更好地利用Swagger。

Swagger与API的关系

Swagger与API的关系紧密，它是用于描述和构建API的工具集。Swagger帮助开发者定义和实现API，并生成交互式的文档，使得API的开发和使用更加方便。具体来说，Swagger可以实现以下几个方面：

• 定义API：Swagger提供了一套标准（如OpenAPI规范），用于描述API的各种细节，如资源、路径、请求参数、响应格式等。
• 生成文档：Swagger可以自动生成API文档，这些文档不仅包含API的定义，还包括交互式界面，允许用户直接在文档中测试API。
• 测试和调试：Swagger提供了测试工具，可以方便地在生成的文档中测试API，快速发现和解决问题。
• 集成到项目中：Swagger可以无缝集成到现有的开发流程中，无论是前端还是后端，都可以使用Swagger来定义和生成API文档。
• 版本控制：Swagger支持多版本的API，可以轻松管理不同版本的API，确保兼容性和稳定性。
• 可视化界面：Swagger生成的文档不仅包含详细的API定义，还提供了一个交互式的界面，使得API的结构和操作一目了然。
• 社区支持：Swagger拥有活跃的社区，提供了丰富的资源和工具，帮助开发者更好地利用Swagger来管理API。

安装和配置Swagger是一个相对简单的过程。下面将详细说明如何在项目中集成Swagger。

下载Swagger

Swagger可以通过多种方式获取，包括官方的GitHub仓库、NPM（对于Node.js项目）等。这里以Node.js项目为例，说明如何通过NPM下载Swagger相关工具。

1. 确保已安装Node.js和npm。如果没有安装，可以从Node.js官网下载安装包，或者使用包管理器如Chocolatey（Windows）或Homebrew（macOS）进行安装。
2. 打开命令行工具（如Windows的cmd或macOS的终端），通过以下命令安装Swagger-Node中间件：

   npm install express swagger-jsdoc swagger-ui-express

   这里，express是Node.js的一个流行的Web应用框架，swagger-jsdoc用于生成Swagger API文档，swagger-ui-express用于生成交互式的Swagger文档界面。

在项目中集成Swagger

接下来，将Swagger集成到你的Node.js项目中。以下是一个详细的步骤和代码示例：

1. 首先，创建一个新的Node.js项目。如果已经有一个现有的项目，可以直接跳到步骤2。

   mkdir my-api-project
   cd my-api-project
   npm init -y

2. 在项目根目录下，创建一个server.js文件，这是你的Web应用的入口文件。

3. 在server.js文件中，引入必要的模块并设置Express应用：

   const express = require('express');
   const swaggerUi = require('swagger-ui-express');
   const swaggerDocument = require('./swagger.json');
   const app = express();
   
   // 设置路由
   app.get('/api/v1', (req, res) => {
    res.send('Hello, welcome to my API!');
   });
   
   // 设置Swagger UI中间件
   app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
   
   // 启动服务器
   const PORT = process.env.PORT || 3000;
   app.listen(PORT, () => {
    console.log(`Server is running on port ${PORT}`);
   });

4. 在项目根目录下，创建一个swagger.json文件，用于定义Swagger API文档。以下是一个简单的Swagger文档定义：

   {
    "openapi": "3.0.0",
    "info": {
      "title": "My API",
      "version": "1.0.0"
    },
    "servers": [
      {
        "url": "http://localhost:3000"
      }
    ],
    "paths": {
      "/api/v1": {
        "get": {
          "summary": "Get welcome message",
          "responses": {
            "200": {
              "description": "OK",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    }
   }

5. 运行项目。在命令行工具中输入以下命令：

   node server.js

   现在，你应该能够在http://localhost:3000/api-docs访问Swagger UI界面，查看生成的API文档。

以上步骤展示了如何在Node.js项目中集成Swagger，并生成交互式的API文档。这不仅提高了API的开发效率，也使得API的使用更加便捷。

创建Swagger文档是一种定义API结构的有效方式。通过定义API路径、方法、参数等，可以清晰地描述API的行为。下面将详细说明如何定义API路径和方法，并添加描述和参数。

定义API路径和方法

API路径（也称作端点）是客户端访问资源的地址。路径定义了资源的位置和请求的方式（如GET、POST、PUT等）。以下是一个简单的API路径定义示例，包括HTTP方法、请求参数和响应格式：

{
  "openapi": "3.0.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "Get a list of users",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "integer" },
                      "name": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a new user",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "integer" },
                    "name": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

在这个示例中，我们定义了一个/users路径，支持GET和POST两种方法。GET方法用于获取用户列表，其返回值是一个包含多个用户对象的数组。每个用户对象包含id和name两个属性。POST方法用于创建新的用户，请求体中需要包含一个name属性，响应则返回创建的用户对象，同样包含id和name属性。

添加描述和参数

在定义API路径和方法的基础上，我们还可以为每个请求和响应添加更详细的描述和参数。这些描述将帮助用户更好地理解API的行为。以下是一个更详细的Swagger文档示例，包含描述和参数定义：

{
  "openapi": "3.0.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "Get a list of users",
        "description": "This endpoint returns a list of all users in the system.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "ID of the user to retrieve. If not provided, all users are returned."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "integer" },
                      "name": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a new user",
        "description": "This endpoint allows you to create a new user.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": { "type": "string" },
                  "email": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "integer" },
                    "name": { "type": "string" },
                    "email": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

在这个示例中，我们增加了两个新的参数：

• GET方法添加了一个名为id的查询参数，用于指定要获取的用户ID。如果未提供此参数，则返回所有用户。
• POST方法请求体中增加了email属性，用于指定新用户的邮箱地址。

这些参数和描述进一步增强了API的可读性和可维护性，使得API的使用更加直观和方便。

示例代码

以下是一个完整的示例代码，展示了如何在Node.js项目中使用Swagger定义API：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
const app = express();

// 设置路由
app.get('/users', (req, res) => {
  const id = req.query.id;
  if (id) {
    // 模拟获取单个用户
    res.json([{ id: id, name: 'User ' + id }]);
  } else {
    // 模拟获取所有用户
    res.json([
      { id: 1, name: 'User 1' },
      { id: 2, name: 'User 2' }
    ]);
  }
});

app.post('/users', (req, res) => {
  const { name, email } = req.body;
  // 模拟创建新用户
  const newUser = { id: Date.now(), name, email };
  res.status = 201;
  res.json(newUser);
});

// 设置Swagger UI中间件
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

// 启动服务器
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

以上代码中，我们定义了两个路由/users，分别实现了GET和POST方法，并使用了前面定义的Swagger文档。GET方法根据查询参数id返回单个用户或所有用户，POST方法接收用户信息并返回新创建的用户。

通过这种方式，可以清晰地定义和实现API，并生成交互式的文档，使得API的开发、测试和维护变得更加高效。

Swagger UI是Swagger提供的一款在线文档生成工具，可以生成交互式的API文档。通过访问Swagger UI界面，用户可以直接查看生成的API文档，进行测试，甚至直接在文档中调用API。下面将详细介绍如何访问Swagger UI界面以及查看生成的API文档。

访问Swagger UI界面

在前面的章节中，我们已经介绍了如何在项目中集成Swagger，并生成了Swagger文档和Swagger UI界面。这里我们将详细说明如何访问Swagger UI界面。

1. 启动项目：确保你的Node.js项目已经运行。在命令行工具中输入node server.js启动项目，或者使用npm start（如果项目中已配置了脚本）。
2. 访问Swagger UI界面：启动项目后，打开浏览器，访问http://localhost:3000/api-docs（假设你的项目运行在本地端口3000）。你应该能够看到Swagger UI界面，如下所示：

在这个界面中，你可以看到API的概述、路径、请求方法、请求参数、响应格式等信息。此外，Swagger UI还提供了交互式的测试功能，允许你直接在界面中测试API。

查看生成的API文档

在Swagger UI界面中，你可以查看生成的API文档，包括API的概述、路径、请求方法、请求参数、响应格式等。以下是如何查看生成的API文档的步骤：

1. 导航到路径：在Swagger UI界面的左侧，点击路径（例如 /users），可以查看该路径的详细信息。
2. 查看请求方法：在路径详情页面中，可以看到支持的请求方法（例如 GET 和 POST）。
3. 查看请求参数：点击请求方法，可以查看请求参数及其描述。例如，对于GET方法，可以查看查询参数（如id）的定义；对于POST方法，可以查看请求体中需要的字段（如name和email）。
4. 查看请求和响应格式：在请求方法页面中，可以看到具体的请求和响应格式。例如，请求体的格式、响应的状态码、响应的内容类型等。
5. 测试API：在请求方法页面中，点击Try it out按钮，可以在界面上直接测试API。输入必要的参数，点击Execute按钮，查看响应结果。

以下是一些具体的示例：

• 查看路径 /users：
  • 支持的方法：GET 和 POST
  • GET 方法
  • 查询参数：id（可选，用于指定要获取的用户ID）
  • 响应格式：返回一个包含多个用户对象的数组，每个对象包含id和name属性。
  • POST 方法
  • 请求体：需要包含name（必填）和email（可选）字段
  • 响应格式：返回创建的用户对象，包含id、name和email属性。

通过这些步骤，你可以全面了解API的定义和行为，并通过Swagger UI的交互界面进行测试。

示例代码

以下是一个完整的示例代码，展示了如何在Node.js项目中使用Swagger定义API，并生成Swagger UI界面：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
const app = express();

// 设置路由
app.get('/users', (req, res) => {
  const id = req.query.id;
  if (id) {
    // 模拟获取单个用户
    res.json([{ id: id, name: 'User ' + id }]);
  } else {
    // 模拟获取所有用户
    res.json([
      { id: 1, name: 'User 1' },
      { id: 2, name: 'User 2' }
    ]);
  }
});

app.post('/users', (req, res) => {
  const { name, email } = req.body;
  // 模拟创建新用户
  const newUser = { id: Date.now(), name, email };
  res.status = 201;
  res.json(newUser);
});

// 设置Swagger UI中间件
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

// 启动服务器
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

在这个示例中，我们定义了两个路由/users，分别实现了GET和POST方法，并使用了前面定义的Swagger文档。GET方法根据查询参数id返回单个用户或所有用户，POST方法接收用户信息并返回新创建的用户。

启动项目后，通过http://localhost:3000/api-docs访问Swagger UI界面，可以查看生成的API文档，并进行测试。

在使用Swagger时，可能会遇到一些常见的问题。这些问题通常与安装、配置、使用过程中的一些错误有关。本节将详细介绍这些问题及其解决方案，帮助大家在遇到问题时能够快速找到解决办法。

常见错误及解决办法

1. Swagger文档未生成或显示不正确

问题描述：启动项目后，访问Swagger UI界面时，发现Swagger文档未生成或显示不正确。
可能原因：

• 未正确安装Swagger相关依赖：确保已经安装了swagger-jsdoc和swagger-ui-express。
• Swagger文档配置错误：检查swagger.json文件中定义的API路径和方法是否正确。
• 缺少Swagger中间件：确保在Express应用中正确设置了Swagger UI中间件。

解决办法：

1. 检查依赖安装：在命令行工具中输入以下命令，确认已安装Swagger相关依赖：

   npm list swagger-jsdoc swagger-ui-express

   如果未安装，可以通过以下命令安装：

   npm install swagger-jsdoc swagger-ui-express

2. 检查Swagger文档配置：确认swagger.json文件中的路径和方法定义是否正确。例如，检查下面的JSON片段是否包含所有必要的API路径和方法：

   {
    "openapi": "3.0.0",
    "info": {
      "title": "My API",
      "version": "1.0.0"
    },
    "paths": {
      "/users": {
        "get": {
          "summary": "Get a list of users",
          "responses": {
            "200": {
              "description": "OK",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": { "type": "integer" },
                        "name": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "post": {
          "summary": "Create a new user",
          "requestBody": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string" }
                  }
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "User created",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "integer" },
                      "name": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
   }

3. 设置Swagger中间件：确保在Express应用中正确设置了Swagger UI中间件。例如：

   const express = require('express');
   const swaggerUi = require('swagger-ui-express');
   const swaggerDocument = require('./swagger.json');
   const app = express();
   
   // 设置路由
   app.get('/users', (req, res) => {
    const id = req.query.id;
    if (id) {
      // 模拟获取单个用户
      res.json([{ id: id, name: 'User ' + id }]);
    } else {
      // 模拟获取所有用户
      res.json([
        { id: 1, name: 'User 1' },
        { id: 2, name: 'User 2' }
      ]);
    }
   });
   
   app.post('/users', (req, res) => {
    const { name, email } = req.body;
    // 模拟创建新用户
    const newUser = { id: Date.now(), name, email };
    res.status = 201;
    res.json(newUser);
   });
   
   // 设置Swagger UI中间件
   app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
   
   // 启动服务器
   const PORT = process.env.PORT || 3000;
   app.listen(PORT, () => {
    console.log(`Server is running on port ${PORT}`);
   });

2. Swagger UI界面加载缓慢或无法加载

问题描述：访问Swagger UI界面时，界面加载缓慢或无法加载。
可能原因：

• 网络问题：网络连接不稳定或较慢。
• 文件路径错误：Swagger UI中间件的路径设置不正确。

解决办法：

1. 检查网络连接：确保网络连接稳定且较快。
2. 检查Swagger UI中间件路径：确认Swagger UI中间件路径设置正确。例如：

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

3. Swagger文档更新后未生效

问题描述：修改Swagger文档后，Swagger UI界面未更新或显示旧文档。
可能原因：

• 缓存问题：浏览器缓存了旧的Swagger文档。
• 配置文件未更新：修改了Swagger文档但未更新swagger.json文件。

解决办法：

1. 清除浏览器缓存：在浏览器中清除缓存，或尝试重新启动浏览器。
2. 更新Swagger文档文件：确认已更新swagger.json文件中的路径和方法定义，并重新启动项目。

优化Swagger文档的技巧

优化Swagger文档可以提高API的可读性和可维护性。以下是一些优化Swagger文档的技巧：

1. 使用description字段：为每个API路径和请求方法添加详细的描述，帮助用户更好地理解API的行为。

   "paths": {
    "/users": {
      "get": {
        "summary": "Get a list of users",
        "description": "This endpoint returns a list of all users in the system.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "integer" },
                      "name": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
   }

2. 使用requestBody和parameters字段：明确定义请求体和查询参数，确保用户能够正确调用API。

   "paths": {
    "/users": {
      "post": {
        "summary": "Create a new user",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": { "type": "string" },
                  "email": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "integer" },
                    "name": { "type": "string" },
                    "email": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
   }

3. 使用tags字段：通过tags字段对API进行分类，便于管理和查看。

   "tags": [
    {
      "name": "Users",
      "description": "Operations with users"
    }
   ],
   "paths": {
    "/users": {
      "tags": ["Users"],
      "get": {
        "summary": "Get a list of users",
        "description": "This endpoint returns a list of all users in the system.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "integer" },
                      "name": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
   }

4. 使用components字段：定义公共部分，如请求和响应格式，减少重复定义，提高文档的一致性。

   "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "email": { "type": "string" }
        }
      }
    }
   },
   "paths": {
    "/users": {
      "get": {
        "summary": "Get a list of users",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/User"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a new user",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/User"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          }
        }
      }
    }
   }

通过这些优化技巧，可以提高Swagger文档的质量，使得API的开发和维护更加高效。

在本篇文章中，我们详细介绍了Swagger入门的相关内容，包括Swagger的定义、作用、安装与配置、创建API文档、使用Swagger UI查看文档以及常见问题的解决方法。通过这些内容的学习，相信你已经掌握了如何使用Swagger来定义和生成高质量的API文档，从而提高API的开发和维护效率。

Swagger入门总结

• Swagger的定义与作用：Swagger是一个用于描述、生成、调用和可视化RESTful风格Web服务的框架，提供了描述API的标准（如OpenAPI规范），以及生成交互式API文档的工具。
• 安装与配置Swagger：通过NPM安装Swagger相关的依赖，并在Node.js项目中集成Swagger，生成交互式的文档界面。
• 创建API文档：通过定义API路径、方法、请求和响应格式，生成详细的API文档。
• 使用Swagger UI：通过Swagger UI访问生成的API文档，查看路径、方法、参数等信息，并进行在线测试。
• 常见问题与解决方法：提供了常见的错误及解决办法，帮助解决使用过程中遇到的问题。

后续学习方向

掌握了Swagger入门知识后，你可以继续深入学习以下内容，以进一步提升你的技能：

• 深入学习OpenAPI规范：进一步理解OpenAPI规范的细节，掌握更多高级特性，如security、examples等。
• 集成Swagger到现有项目：将Swagger集成到现有的Web应用中，生成并维护API文档。
• 自动化生成Swagger文档：结合代码生成工具（如Swagger-Codegen），自动化生成Swagger文档，减少手动编写文档的工作量。
• 使用Swagger进行API测试：使用Swagger提供的测试功能，进行API的测试和调试，提高开发效率。
• 参与Swagger社区：加入Swagger的社区，参与交流和贡献，获取更多资源和支持。

通过继续学习和实践，你将能够更加熟练地使用Swagger来开发和维护高质量的API文档，从而提高项目的开发效率和质量。

示例代码

以下是一个完整的示例代码，展示了如何在Node.js项目中集成Swagger，并生成交互式的API文档：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
const app = express();

// 设置路由
app.get('/users', (req, res) => {
  const id = req.query.id;
  if (id) {
    // 模拟获取单个用户
    res.json([{ id: id, name: 'User ' + id }]);
  } else {
    // 模拟获取所有用户
    res.json([
      { id: 1, name: 'User 1' },
      { id: 2, name: 'User 2' }
    ]);
  }
});

app.post('/users', (req, res) => {
  const { name, email } = req.body;
  // 模拟创建新用户
  const newUser = { id: Date.now(), name, email };
  res.status = 201;
  res.json(newUser);
});

// 设置Swagger UI中间件
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

// 启动服务器
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

通过这个示例代码，你可以在本地启动一个Node.js项目，并访问Swagger UI界面，查看生成的API文档。这将帮助你更好地理解如何在实际项目中使用Swagger，从而提高项目的开发效率。