Практическое руководство по Swagger: API управления книгами

Это руководство проведет вас через реализацию API системы управления книгами на основе Swagger. Основные возможности включают:

• CRUD-операции с книгами
• Постраничные запросы
• Фильтрация по условиям
• Автоматическая генерация документации API
• Онлайн-тестирование API

Технологический стек:

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

Подготовка окружения

Установите Node.js

Убедитесь, что Node.js установлен в вашей системе (рекомендуется версия 14.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：

Функциональное тестирование API

Запуск сервера

Используйте следующую команду для запуска сервера:

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

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

6.2 Доступ к документации Swagger

Откройте браузер и перейдите по адресу: http://localhost:3000/api-docs

Использование Swagger для тестирования API

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

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