Introducción a Swagger

Swagger es un conjunto de herramientas de software de código abierto que ayuda a diseñar, construir, documentar y consumir servicios web RESTful. Es especialmente útil para generar documentación interactiva y detallada de las APIs, lo que facilita la comprensión y el uso de las mismas tanto para desarrolladores como para otros stakeholders.

¿Por qué usar Swagger?

Documentación Interactiva: Swagger genera una interfaz web interactiva donde los usuarios pueden probar las diferentes rutas de la API.
Estándar Abierto: Swagger sigue el estándar OpenAPI, lo que asegura compatibilidad y consistencia.
Facilita la Comunicación: Proporciona una forma clara y precisa de comunicar cómo funciona la API.
Generación Automática de Código: Swagger puede generar código cliente y servidor en varios lenguajes de programación.

Instalación y Configuración de Swagger

Instalación

Para empezar a usar Swagger, primero necesitas instalar las herramientas necesarias. En este ejemplo, usaremos swagger-ui-express para una aplicación Node.js.

npm install swagger-ui-express swagger-jsdoc

Configuración Básica

A continuación, configuraremos Swagger en una aplicación Express.

Crear un archivo de configuración de Swagger: swaggerConfig.js

const swaggerJsDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const swaggerOptions = {
  swaggerDefinition: {
    openapi: '3.0.0',
    info: {
      title: 'API de Ejemplo',
      version: '1.0.0',
      description: 'Documentación de la API de Ejemplo usando Swagger',
      contact: {
        name: 'Desarrollador',
        email: '[email protected]'
      },
      servers: [
        {
          url: 'http://localhost:3000',
          description: 'Servidor de Desarrollo'
        }
      ]
    }
  },
  apis: ['./routes/*.js'] // Ruta a los archivos que contienen anotaciones de Swagger
};

const swaggerDocs = swaggerJsDoc(swaggerOptions);

module.exports = { swaggerUi, swaggerDocs };

Integrar Swagger en la aplicación Express: app.js

const express = require('express');
const { swaggerUi, swaggerDocs } = require('./swaggerConfig');

const app = express();

// Rutas de la API
const apiRoutes = require('./routes/apiRoutes');
app.use('/api', apiRoutes);

// Configuración de Swagger
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Servidor corriendo en http://localhost:${PORT}`);
  console.log(`Documentación de la API disponible en http://localhost:${PORT}/api-docs`);
});

Anotaciones de Swagger

Para que Swagger pueda generar la documentación, necesitas agregar anotaciones en tus rutas. Aquí tienes un ejemplo básico:

// routes/apiRoutes.js
const express = require('express');
const router = express.Router();

/**
 * @swagger
 * /api/users:
 *   get:
 *     summary: Obtiene una lista de usuarios
 *     responses:
 *       200:
 *         description: Lista de usuarios
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: object
 *                 properties:
 *                   id:
 *                     type: integer
 *                     example: 1
 *                   name:
 *                     type: string
 *                     example: John Doe
 */
router.get('/users', (req, res) => {
  res.json([
    { id: 1, name: 'John Doe' },
    { id: 2, name: 'Jane Doe' }
  ]);
});

module.exports = router;

Ejercicio Práctico

Ejercicio 1: Documentar una Ruta

Objetivo: Documentar la ruta /api/products que devuelve una lista de productos.
Pasos:
- Añade una nueva ruta en apiRoutes.js.
- Usa anotaciones de Swagger para documentar la ruta.

/**
 * @swagger
 * /api/products:
 *   get:
 *     summary: Obtiene una lista de productos
 *     responses:
 *       200:
 *         description: Lista de productos
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: object
 *                 properties:
 *                   id:
 *                     type: integer
 *                     example: 1
 *                   name:
 *                     type: string
 *                     example: Producto A
 *                   price:
 *                     type: number
 *                     example: 19.99
 */
router.get('/products', (req, res) => {
  res.json([
    { id: 1, name: 'Producto A', price: 19.99 },
    { id: 2, name: 'Producto B', price: 29.99 }
  ]);
});

Solución

// routes/apiRoutes.js
const express = require('express');
const router = express.Router();

/**
 * @swagger
 * /api/products:
 *   get:
 *     summary: Obtiene una lista de productos
 *     responses:
 *       200:
 *         description: Lista de productos
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: object
 *                 properties:
 *                   id:
 *                     type: integer
 *                     example: 1
 *                   name:
 *                     type: string
 *                     example: Producto A
 *                   price:
 *                     type: number
 *                     example: 19.99
 */
router.get('/products', (req, res) => {
  res.json([
    { id: 1, name: 'Producto A', price: 19.99 },
    { id: 2, name: 'Producto B', price: 29.99 }
  ]);
});

module.exports = router;

Conclusión

Swagger es una herramienta poderosa que facilita la documentación y el uso de APIs RESTful. A través de su interfaz interactiva y su capacidad para generar código, Swagger mejora la comunicación entre desarrolladores y otros stakeholders, asegurando que todos entiendan cómo interactuar con la API. En este módulo, hemos aprendido a instalar, configurar y usar Swagger para documentar nuestras APIs, lo que nos permitirá crear documentación clara y precisa para nuestros proyectos.

En el siguiente módulo, exploraremos otros frameworks y herramientas populares para el desarrollo de APIs RESTful, lo que nos permitirá elegir las mejores opciones para nuestros proyectos específicos.

Swagger para Documentación

Introducción a Swagger

¿Por qué usar Swagger?

Instalación y Configuración de Swagger

Instalación

Configuración Básica

Anotaciones de Swagger

Ejercicio Práctico

Ejercicio 1: Documentar una Ruta

Solución

Conclusión

Curso de REST API: Principios de Diseño y Desarrollo de APIs RESTful

Módulo 1: Introducción a las APIs RESTful

Módulo 2: Diseño de APIs RESTful

Módulo 3: Desarrollo de APIs RESTful

Módulo 4: Buenas Prácticas y Seguridad

Módulo 5: Herramientas y Frameworks

Módulo 6: Casos de Estudio y Proyectos