Swagger 实战教程：图书管理 API

本教程将带您实现一个基于Swagger的图书管理系统API，主要功能包括：

• 图书的增删改查操作
• 分页查询
• 条件过滤
• API文档自动生成
• 在线接口测试

技术栈：

• Node.js + Express
• Swagger UI Express
• Swagger JSDoc

环境准备

安装Node.js

确保您的系统已安装 Node.js（建议使用v14.0.0或更高版本）。

检查环境

node -v
npm -v

项目初始化

创建项目目录

mkdir book-management-api
cd book-management-api
npm init -y

安装依赖包

npm install express cors swagger-ui-express swagger-jsdoc nodemon --save

创建基础项目结构

book-management-api/
├── node_modules/
├── models/
│   └── book.js
├── routes/
│   └── books.js
├── middleware/
│   └── auth.js
├── swagger/
│   └── swagger.js
├── app.js
└── package.json

创建入口文件 app.js

API 设计与实现

创建图书模型

在models/book.js 中创建一个简单的内存数据模型：

实现路由控制器

在 routes/books.js 中实现 API 路由：

Swagger 文档配置

配置 Swagger

创建 swagger/swagger.js 文件：

添加认证中间件

创建 middleware/auth.js：

接口功能测试

启动服务

使用以下命令启动服务：

# 如果已配置了package.json中的scripts，执行：
npm start

# 或者直接使用nodemon
npx nodemon app.js

6.2 访问Swagger文档

打开浏览器访问： http://localhost:3000/api-docs

使用 Swagger 测试接口

1. 获取所有图书

   • 点击 GET /api/books 接口
   • 点击 "Try it out" 按钮
   • 可以设置分页参数 page 和 limit，以及过滤条件
   • 点击 "Execute" 按钮发送请求
   • 观察结果

2. 创建新图书

   • 点击 POST /api/books 接口
   • 点击 "Try it out" 按钮

   • 在请求体中填入图书信息，例如：

     {
         "title": "RESTful API设计",
         "author": "Martin Fowler",
         "publishDate": "2020-01-01",
         "isbn": "978-1234567890",
         "category": "编程"
     }
     

   • 点击 "Execute" 按钮发送请求
   • 观察结果

3. 获取、更新和删除

   • 使用类似方法测试其他接口

常见问题排查

跨域问题

如果前端应用和 API 不在同一域下运行，可能会遇到跨域问题。我们已经在应用入口配置了 CORS 中间件：

app.use(cors());

如果需要更精细的控制，可以这样配置：

认证配置错误

认证问题通常出现在以下几个方面：

1. JWT 配置错误

   确保 JWT_SECRET 环境变量已正确设置：

   // 在应用启动时检查
   if (!process.env.JWT_SECRET) {
     console.warn('警告: JWT_SECRET环境变量未设置，认证可能不安全');
   }        
   

2. 认证中间件使用错误

   确保在需要认证的路由上正确应用中间件：

   const auth = require('../middleware/auth');
   
   // 公开路由 - 无需认证
   router.get('/', (req, res) => { /* ... */ });
   
   // 受保护路由 - 需要认证
   router.post('/', auth, (req, res) => { /* ... */ });
   router.put('/:id', auth, (req, res) => { /* ... */ });
   router.delete('/:id', auth, (req, res) => { /* ... */ });
   

3. Swagger文档中的认证配置

   更新Swagger配置以支持Bearer Token认证：

   // swagger/swagger.js
   const options = {
     definition: {
       // ... 其他配置 ...
       components: {
         securitySchemes: {
           bearerAuth: {
             type: 'http',
             scheme: 'bearer',
             bearerFormat: 'JWT'
           }
         }
       },
       security: [
         {
           bearerAuth: []
         }
       ]
     },
     // ... 其他配置 ...
   };
   

4. 请求头配置

   确保客户端请求时正确设置了认证头：

   // 前端示例代码 - 使用fetch API
   const token = localStorage.getItem('token');
   
   fetch('http://localhost:3000/api/books', {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
       'Authorization': `Bearer ${token}`
     },
     body: JSON.stringify(bookData)
   })
   .then(response => response.json())
   .then(data => console.log(data))
   .catch(error => console.error('错误:', error));
   

Swagger 文档不更新

如果更新了 JSDoc 注释但 Swagger 文档没有更新，尝试以下解决方案：

1. 确保路径配置正确

   // swagger/swagger.js
   const options = {
     // ... 其他配置 ...
     apis: ['./routes/*.js', './models/*.js'] // 确保包含所有需要生成文档的文件
   };
   

2. 重启服务器

   有时候需要重启服务器才能看到新的Swagger文档。

3. 清除浏览器缓存

   使用Ctrl+F5强制刷新页面。

进阶功能

添加 API 版本控制

修改应用入口文件：

// app.js
// ... 其他导入 ...

// API v1
app.use('/api/v1/books', booksRouter);

// 为未来的API v2预留
// app.use('/api/v2/books', booksRouterV2);

// ... 其他代码 ...

添加请求验证

使用 Express 验证中间件（如express-validator）：

npm install express-validator --save

然后在路由中使用：

添加响应压缩

使用压缩中间件减小响应体积：

npm install compression --save

然后在应用入口文件中添加：

// app.js
const compression = require('compression');

// ... 其他代码 ...

// 启用压缩
app.use(compression());

// ... 其他代码 ...

添加响应缓存

为了提高性能，可以添加响应缓存：

npm install apicache --save

然后在应用入口中使用：

// app.js
const apicache = require('apicache');
const cache = apicache.middleware;

// ... 其他代码 ...

// 缓存GET请求5分钟
app.use('/api', cache('5 minutes'));

// ... 其他代码 ...

添加请求限流

防止 API 滥用：

npm install express-rate-limit --save

然后在应用入口中使用：

// app.js
const rateLimit = require('express-rate-limit');

// ... 其他代码 ...

// 创建限流中间件
const apiLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15分钟
  max: 100, // 每个IP在windowMs时间内最多100个请求
  message: '来自此IP的请求过多，请稍后再试'
});

// 应用限流中间件
app.use('/api', apiLimiter);

// ... 其他代码 ...