Tutorial práctico de Swagger: API de gestión de libros
Este tutorial le guiará para implementar una API de sistema de gestión de libros basada en Swagger. Las funciones principales incluyen:
- Operaciones CRUD de libros
- Consulta paginada
- Filtrado por condiciones
- Generación automática de documentación de API
- Pruebas de interfaz en línea
Pila tecnológica:
- Node.js + Express
- Swagger UI Express
- Swagger JSDoc
Preparación del entorno
Instalar Node.js
Asegúrese de que Node.js esté instalado en su sistema (se recomienda usar v14.0.0 o superior).
Verificar el entorno
node -v npm -v
Inicialización del proyecto
Crear el directorio del proyecto
mkdir book-management-api cd book-management-api npm init -y
Instalar paquetes de dependencias
npm install express cors swagger-ui-express swagger-jsdoc nodemon --save
Crear la estructura básica del proyecto
book-management-api/ ├── node_modules/ ├── models/ │ └── book.js ├── routes/ │ └── books.js ├── middleware/ │ └── auth.js ├── swagger/ │ └── swagger.js ├── app.js └── package.json
Crear el archivo de entrada app.js
Ejemplo
const cors = require('cors');
const swaggerUi = require('swagger-ui-express');
const swaggerSpec = require('./swagger/swagger');
const booksRouter = require('./routes/books');
const app = express();
const PORT = process.env.PORT || 3000;
// Middleware
app.use(cors());
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
// Rutas de API
app.use('/api/books', booksRouter);
// Documentación de Swagger
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
// Iniciar servidor
app.listen(PORT, () => {
console.log(`Servicio iniciado, visita http://localhost:${PORT}`);
console.log(`Dirección de la documentación de API: http://localhost:${PORT}/api-docs`);
});
Diseño e implementación de la API
Crear el modelo de libro
Enmodels/book.jsCree un modelo de datos simple en memoria:
Ejemplo
let books = [
{ id: 1, title: 'Entendiendo JavaScript en profundidad', author: 'Douglas Crockford', publishDate: '2008-01-01', isbn: '978-0596517748', category: 'Programación' },
{ id: 2, title: 'Práctica de Node.js', author: 'Alex Young', publishDate: '2014-08-01', isbn: '978-1617290572', category: 'Programación' },
{ id: 3, title: 'Los tres cuerpos', author: 'Liu Cixin', publishDate: '2008-01-01', isbn: '978-7536692387', category: 'Ciencia ficción' }
];
let nextId = 4;
module.exports = {
// Obtener todos los libros
getAll: (page = 1, limit = 10, filter = {}) => {
let result = [...books];
// Aplicar condiciones de filtro
if (filter.category) {
result = result.filter(book => book.category === filter.category);
}
if (filter.author) {
result = result.filter(book => book.author.includes(filter.author));
}
if (filter.title) {
result = result.filter(book => book.title.includes(filter.title));
}
// Calcular paginación
const startIndex = (page - 1) * limit;
const endIndex = page * limit;
return {
total: result.length,
page: page,
limit: limit,
data: result.slice(startIndex, endIndex)
};
},
// Obtener un solo libro
getById: (id) => {
return books.find(book => book.id === id);
},
// Crear un libro
create: (book) => {
const newBook = { ...book, id: nextId++ };
books.push(newBook);
return newBook;
},
// Actualizar un libro
update: (id, bookData) => {
const index = books.findIndex(book => book.id === id);
if (index !== -1) {
books[index] = { ...books[index], ...bookData };
return books[index];
}
return null;
},
// Eliminar un libro
delete: (id) => {
const index = books.findIndex(book => book.id === id);
if (index !== -1) {
const deletedBook = books[index];
books.splice(index, 1);
return deletedBook;
}
return null;
}
};
Implementar el controlador de rutas
Enroutes/books.jsImplemente las rutas de API:
Ejemplo
const express = require('express');
const router = express.Router();
const Book = require('../models/book');
/**
* @swagger
* components:
* schemas:
* Book:
* type: object
* required:
* - title
* - author
* - isbn
* properties:
* id:
* type: integer
* description: ID del libro
* title:
* type: string
* description: Título del libro
* author:
* type: string
* description: Autor
* publishDate:
* type: string
* format: date
* description: Fecha de publicación
* isbn:
* type: string
* description: Número de ISBN
* category:
* type: string
* description: Categoría del libro
*/
/**
* @swagger
* /api/books:
* get:
* summary: Obtener lista de libros
* description: Devuelve todos los libros, admite paginación y filtros
* parameters:
* - in: query
* name: page
* schema:
* type: integer
* default: 1
* description: Número de página
* - in: query
* name: limit
* schema:
* type: integer
* default: 10
* description: Cantidad por página
* - in: query
* name: category
* schema:
* type: string
* description: Filtrar por categoría
* - in: query
* name: author
* schema:
* type: string
* description: Filtrar por autor
* - in: query
* name: title
* schema:
* type: string
* description: Filtrar por título
* responses:
* 200:
* description: Lista de libros obtenida con éxito
* content:
* application/json:
* schema:
* type: object
* properties:
* total:
* type: integer
* page:
* type: integer
* limit:
* type: integer
* data:
* type: array
* items:
* $ref: '#/components/schemas/Book'
*/
router.get('/', (req, res) => {
const page = parseInt(req.query.page) || 1;
const limit = parseInt(req.query.limit) || 10;
const filter = {};
if (req.query.category) filter.category = req.query.category;
if (req.query.author) filter.author = req.query.author;
if (req.query.title) filter.title = req.query.title;
const result = Book.getAll(page, limit, filter);
res.json(result);
});
/**
* @swagger
* /api/books/{id}:
* get:
* summary: Obtener un solo libro
* description: Obtiene la información detallada de un libro específico mediante su ID
* parameters:
* - in: path
* name: id
* required: true
* schema:
* type: integer
* description: ID del libro
* responses:
* 200:
* description: Libro obtenido con éxito
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Book'
* 404:
* description: El libro no existe
*/
router.get('/:id', (req, res) => {
const id = parseInt(req.params.id);
const book = Book.getById(id);
if (book) {
res.json(book);
} else {
res.status(404).json({ message: 'El libro no existe' });
}
});
/**
* @swagger
* /api/books:
* post:
* summary: Crear un nuevo libro
* description: Agrega un nuevo libro al sistema
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required:
* - title
* - author
* - isbn
* properties:
* title:
* type: string
* author:
* type: string
* publishDate:
* type: string
* format: date
* isbn:
* type: string
* category:
* type: string
* responses:
* 201:
* description: Libro creado con éxito
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Book'
* 400:
* description: Datos de entrada no válidos
*/
router.post('/', (req, res) => {
// Validación simple
if (!req.body.title || !req.body.author || !req.body.isbn) {
return res.status(400).json({ message: 'El título, el autor y el ISBN son campos obligatorios' });
}
const newBook = Book.create(req.body);
res.status(201).json(newBook);
});
/**
* @swagger
* /api/books/{id}:
* put:
* summary: Actualizar un libro
* description: Actualiza la información de un libro específico mediante su ID
* parameters:
* - in: path
* name: id
* required: true
* schema:
* type: integer
* description: ID del libro
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* title:
* type: string
* author:
* type: string
* publishDate:
* type: string
* format: date
* isbn:
* type: string
* category:
* type: string
* responses:
* 200:
* description: Libro actualizado con éxito
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Book'
* 404:
* description: El libro no existe
*/
router.put('/:id', (req, res) => {
const id = parseInt(req.params.id);
const updatedBook = Book.update(id, req.body);
if (updatedBook) {
res.json(updatedBook);
} else {
res.status(404).json({ message: 'El libro no existe' });
}
});
/**
* @swagger
* /api/books/{id}:
* delete:
* summary: Eliminar un libro
* description: Elimina un libro específico mediante su ID
* parameters:
* - in: path
* name: id
* required: true
* schema:
* type: integer
* description: ID del libro
* responses:
* 200:
* description: Libro eliminado con éxito
* 404:
* description: El libro no existe
*/
router.delete('/:id', (req, res) => {
const id = parseInt(req.params.id);
const deletedBook = Book.delete(id);
if (deletedBook) {
res.json({ message: 'Libro eliminado con éxito', book: deletedBook });
} else {
res.status(404).json({ message: 'El libro no existe' });
}
});
module.exports = router;
Configuración de la documentación de Swagger
Configurar Swagger
Crearswagger/swagger.jsarchivo:
Ejemplo
const swaggerJsdoc = require('swagger-jsdoc');
const options = {
definition: {
openapi: '3.0.0',
info: {
title: 'API de gestión de libros',
version: '1.0.0',
description: 'API de sistema de gestión de libros construida con Express y Swagger',
contact: {
name: 'Desarrollador',
email: 'dev@example.com'
}
},
servers: [
{
url: 'http://localhost:3000',
description: 'Servidor de desarrollo'
}
]
},
// Escanea todos los archivos JS que contienen anotaciones
apis: ['./routes/*.js']
};
const swaggerSpec = swaggerJsdoc(options);
module.exports = swaggerSpec;
Agregar middleware de autenticación
Crearmiddleware/auth.js:
Ejemplo
const jwt = require('jsonwebtoken');
// Middleware simple de verificación JWT
const authMiddleware = (req, res, next) => {
const token = req.header('Authorization')?.replace('Bearer ', '');
if (!token) {
return res.status(401).json({ message: 'No se proporcionó un token de autenticación' });
}
try {
// En una aplicación real, aquí se debe verificar el token JWT
// const decoded = jwt.verify(token, process.env.JWT_SECRET);
// req.user = decoded.user;
// Para simplificar el tutorial, omitimos la verificación
req.user = { id: 1, role: 'admin' };
next();
} catch (error) {
return res.status(401).json({ message: 'Token de autenticación no válido' });
}
};
module.exports = authMiddleware;
Pruebas de funcionalidad de las interfaces
Iniciar el servicio
Inicie el servicio con el siguiente comando:
# 如果已配置了package.json中的scripts,执行: npm start # 或者直接使用nodemon npx nodemon app.js
6.2 Acceder a la documentación de Swagger
Abra el navegador y visite: http://localhost:3000/api-docs
Usar Swagger para probar las interfaces
-
Obtener todos los libros
- Haga clic en el endpoint GET /api/books
- Haga clic en el botón "Try it out"
- Puede configurar los parámetros de paginación page y limit, así como las condiciones de filtro
- Haga clic en el botón "Execute" para enviar la solicitud
- Observar el resultado
-
Crear un nuevo libro
- Haga clic en el endpoint POST /api/books
- Haga clic en el botón "Try it out"
Complete la información del libro en el cuerpo de la solicitud, por ejemplo:
{ "title": "RESTful API设计", "author": "Martin Fowler", "publishDate": "2020-01-01", "isbn": "978-1234567890", "category": "编程" }- Haga clic en el botón "Execute" para enviar la solicitud
- Observar el resultado
-
Obtener, actualizar y eliminar
- Pruebe otras interfaces con un método similar
Solución de problemas comunes
Problema de CORS
Si la aplicación frontend y la API no se ejecutan en el mismo dominio, puede encontrar problemas de uso compartido de recursos entre orígenes (CORS). Ya hemos configurado el middleware CORS en el punto de entrada de la aplicación:
app.use(cors());
Si necesita un control más fino, puede configurarlo así:
Ejemplo
origin: ['http://localhost:8080', 'https://your-frontend-domain.com'],
methods: ['GET', 'POST', 'PUT', 'DELETE'],
allowedHeaders: ['Content-Type', 'Authorization'],
credentials: true
};
app.use(cors(corsOptions));
Error de configuración de autenticación
Los problemas de autenticación suelen aparecer en los siguientes aspectos:
-
Error de configuración de JWT
Asegúrese de que
JWT_SECRETlas variables de entorno estén configuradas correctamente:// 在应用启动时检查 if (!process.env.JWT_SECRET) { console.warn('警告: JWT_SECRET环境变量未设置,认证可能不安全'); } -
Uso incorrecto del middleware de autenticación
Asegúrese de aplicar correctamente el middleware en las rutas que requieren autenticación:
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) => { /* ... */ }); -
Configuración de autenticación en la documentación de Swagger
Actualice la configuración de Swagger para admitir la autenticación con Bearer Token:
// swagger/swagger.js const options = { definition: { // ... 其他配置 ... components: { securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' } } }, security: [ { bearerAuth: [] } ] }, // ... 其他配置 ... }; -
Configuración de los encabezados de solicitud
Asegúrese de que el cliente establezca correctamente el encabezado de autenticación al realizar la solicitud:
// 前端示例代码 - 使用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));
La documentación de Swagger no se actualiza
Si ha actualizado los comentarios JSDoc pero la documentación de Swagger no se ha actualizado, pruebe las siguientes soluciones:
-
Asegúrese de que la configuración de rutas sea correcta
// swagger/swagger.js const options = { // ... 其他配置 ... apis: ['./routes/*.js', './models/*.js'] // 确保包含所有需要生成文档的文件 }; -
Reinicie el servidor
A veces es necesario reiniciar el servidor para ver la nueva documentación de Swagger.
-
Limpie la caché del navegador
Utilice Ctrl+F5 para forzar la actualización de la página.
Funciones avanzadas
Agregar control de versiones de API
Modifique el archivo de entrada de la aplicación:
// app.js
// ... 其他导入 ...
// API v1
app.use('/api/v1/books', booksRouter);
// 为未来的API v2预留
// app.use('/api/v2/books', booksRouterV2);
// ... 其他代码 ...
Agregar validación de solicitudes
Utilice middleware de validación de Express (comoexpress-validator):
npm install express-validator --save
Luego úselo en las rutas:
Ejemplo
const { body, validationResult } = require('express-validator');
// Reglas de validación para crear un libro
const validateBook = [
body('title').notEmpty().withMessage('El título no puede estar vacío'),
body('author').notEmpty().withMessage('El autor no puede estar vacío'),
body('isbn').notEmpty().withMessage('El ISBN no puede estar vacío')
.matches(/^(?=(?:\D*\d){10}(?:(?:\D*\d){3})?$)[\d-]+$/).withMessage('Formato de ISBN no válido'),
body('publishDate').optional().isDate().withMessage('Formato de fecha de publicación no válido'),
// Middleware de procesamiento de resultados de validación
(req, res, next) => {
const errors = validationResult(req);
if (!errors.isEmpty()) {
return res.status(400).json({ errors: errors.array() });
}
next();
}
];
// Usar la validación en las rutas
router.post('/', validateBook, (req, res) => {
// ... Código para crear el libro ...
});
Agregar compresión de respuestas
Use middleware de compresión para reducir el tamaño de las respuestas:
npm install compression --save
Luego agréguelo en el archivo de entrada de la aplicación:
// app.js
const compression = require('compression');
// ... 其他代码 ...
// 启用压缩
app.use(compression());
// ... 其他代码 ...
Agregar caché de respuestas
Para mejorar el rendimiento, puede agregar caché de respuestas:
npm install apicache --save
Luego úselo en el punto de entrada de la aplicación:
// app.js
const apicache = require('apicache');
const cache = apicache.middleware;
// ... 其他代码 ...
// 缓存GET请求5分钟
app.use('/api', cache('5 minutes'));
// ... 其他代码 ...
Agregar limitación de solicitudes
Para prevenir el abuso de la API:
npm install express-rate-limit --save
Luego úselo en el punto de entrada de la aplicación:
// 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);
// ... 其他代码 ... Otras extensiones