Swagger Hands-on Tutorial: Book Management API

This tutorial will guide you through implementing a Swagger-based Book Management System API. The main features include:

• CRUD operations for books
• Paginated queries
• Condition-based filtering
• Automatic API documentation generation
• Online API testing

Tech stack:

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

Environment Preparation

Install Node.js

Ensure that Node.js is installed on your system (v14.0.0 or higher recommended).

Check Environment

node -v
npm -v

Project Initialization

Create Project Directory

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

Install Dependencies

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

Create Basic Project Structure

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

Create Entry File app.js

API Design and Implementation

Create Book Model

Inmodels/book.jsCreate a simple in-memory data model:

Implement Route Controller

Inroutes/books.jsImplement API routes:

Swagger Documentation Configuration

Configure Swagger

Createswagger/swagger.jsFile:

Add Authentication Middleware

Createmiddleware/auth.js：

API Functional Testing

Start Server

Use the following command to start the server:

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

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

6.2 Access Swagger Documentation

Open a browser and visit: http://localhost:3000/api-docs

Use Swagger to Test APIs

1. Get all books

   • Click the GET /api/books endpoint
   • Click the "Try it out" button
   • You can set the pagination parameters page and limit, and filter conditions
   • Click the "Execute" button to send the request
   • Observe the results

2. Create a new book

   • Click the POST /api/books endpoint
   • Click the "Try it out" button

   • Fill in the book information in the request body, for example:

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

   • Click the "Execute" button to send the request
   • Observe the results

3. Get, Update, and Delete

   • Test other endpoints using similar methods

Troubleshooting Common Issues

Cross-Origin Issue

If the frontend application and API are not running on the same domain, you may encounter cross-origin issues. We have already configured CORS middleware at the application entry point:

app.use(cors());

If finer control is needed, you can configure it like this:

Authentication Configuration Error

Authentication issues usually appear in the following areas:

1. JWT configuration error

   EnsureJWT_SECRETEnvironment variables are set correctly:

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

2. Authentication middleware used incorrectly

   Make sure the middleware is correctly applied to routes that require authentication:

   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. Authentication configuration in Swagger documentation

   Update Swagger configuration to support Bearer Token authentication:

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

4. Request header configuration

   Ensure the client correctly sets the authentication header when making requests:

   // 前端示例代码 - 使用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 Documentation Not Updating

If you update JSDoc comments but the Swagger documentation does not update, try the following solutions:

1. Ensure the path configuration is correct

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

2. Restart the server

   Sometimes you need to restart the server to see the new Swagger documentation.

3. Clear browser cache

   Use Ctrl+F5 to force refresh the page.

Advanced Features

Add API Versioning

Modify the application entry file:

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

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

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

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

Add Request Validation

Use Express validation middleware (such asexpress-validator）：

npm install express-validator --save

Then use it in the route:

Add Response Compression

Use compression middleware to reduce response size:

npm install compression --save

Then add it to the application entry file:

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

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

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

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

Add Response Caching

To improve performance, you can add response caching:

npm install apicache --save

Then use it at the application entry point:

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

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

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

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

Add Request Rate Limiting

Prevent API abuse:

npm install express-rate-limit --save

Then use it at the application entry point:

// 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);

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