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 express = require('express');
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

// models/book.js
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

// routes/books.js
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

// swagger/swagger.js
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

// middleware/auth.js
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

  1. 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
  2. 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
  3. 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

const corsOptions = {
  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:

  1. Error de configuración de JWT

    Asegúrese de queJWT_SECRETlas variables de entorno estén configuradas correctamente:

    // 在应用启动时检查
    if (!process.env.JWT_SECRET) {
      console.warn('警告: JWT_SECRET环境变量未设置,认证可能不安全');
    }        
    
  2. 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) => { /* ... */ });
    
  3. 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: []
          }
        ]
      },
      // ... 其他配置 ...
    };
    
  4. 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:

  1. Asegúrese de que la configuración de rutas sea correcta

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

    A veces es necesario reiniciar el servidor para ver la nueva documentación de Swagger.

  3. 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

// routes/books.js
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