16.12. Creando un CRUD con NodeJS y MongoDB: Documentación API

Una de las partes más cruciales del desarrollo de API es su documentación. Una API bien documentada es una herramienta poderosa para los desarrolladores, ya que facilita su uso y comprensión. En este capítulo, cubriremos cómo documentar una API creada con NodeJS y MongoDB, enfocándonos en un CRUD (Crear, Leer, Actualizar, Eliminar).

Comenzaremos creando una nueva ruta en nuestra aplicación NodeJS. Usaremos Express, un marco popular para NodeJS, para crear nuestras rutas. Nuestra ruta será responsable de manejar todas las operaciones CRUD para un recurso específico. Usaremos MongoDB, una base de datos NoSQL, para almacenar nuestros datos.

Primero, definamos nuestra ruta. En nuestro archivo de rutas, agregamos el siguiente código:

const expresar = requerir('expresar');
enrutador constante = express.Router();
const ResourceController = require('../controllers/resourceController');

enrutador.get('/', ResourceController.getAll);
router.post('/', ResourceController.create);
router.get('/:id', ResourceController.getOne);
router.put('/:id', ResourceController.update);
router.delete('/:id', ResourceController.delete);

módulo.exportaciones = enrutador;

Este código define una nueva ruta que maneja todas las operaciones CRUD para un recurso. ResourceController es un controlador que crearemos en breve y que manejará la lógica de cada operación.

Ahora creemos nuestro controlador. En un archivo nuevo, agregue el siguiente código:

const Recurso = require('../modelos/recurso');

exports.getAll = async (req, res) => {
    recursos constantes = esperar recurso.find();
    res.json(recursos);
};

exportaciones.create = async (req, res) => {
    const nuevoRecurso = nuevo Recurso(req.body);
    recurso constante = esperar nuevoRecurso.save();
    res.json(recurso);
};

exports.getOne = async (req, res) => {
    recurso constante = esperar Resource.findById(req.params.id);
    res.json(recurso);
};

exports.update = async (req, res) => {
    recurso const = await Resource.findByIdAndUpdate(req.params.id, req.body, {nuevo: verdadero});
    res.json(recurso);
};

exports.delete = async (req, res) => {
    espere Resource.findByIdAndRemove(req.params.id);
    res.json({mensaje: 'Recurso eliminado'});
};

Este código define un controlador que maneja todas las operaciones CRUD para un recurso. Utiliza el modelo de recursos que crearemos en breve para interactuar con nuestra base de datos MongoDB.

Ahora, creemos nuestro modelo. En un archivo nuevo, agregue el siguiente código:

const mangosta = require('mangosta');

const ResourceSchema = nueva mangosta.Schema({
    nombre: {
        tipo: cadena,
        requerido: verdadero
    },
    descripción: {
        tipo: cadena,
        requerido: verdadero
    }
});

módulo.exportaciones = mangosta.model('Recurso', ResourceSchema);

Este código define una plantilla para nuestros recursos. Utiliza Mongoose, una biblioteca popular para MongoDB, para definir un esquema para nuestros datos.

Ahora que tenemos nuestra API configurada, es hora de documentarla. La documentación es crucial para garantizar que otros desarrolladores puedan comprender y utilizar nuestra API correctamente. Hay varias herramientas disponibles para documentar las API, pero una de las más populares es Swagger.

Swagger es una herramienta de documentación de API que permite a los desarrolladores definir la estructura de su API utilizando un formato de descripción de API. Genera una interfaz de usuario interactiva que permite a los desarrolladores explorar y probar la API.

Para usar Swagger, primero necesitamos instalar el paquete swagger-ui-express:

npm instala swagger-ui-express

A continuación, podemos agregar el siguiente código a nuestro archivo de rutas:

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

router.use('/api-docs', swaggerUi.serve);
router.get('/api-docs', swaggerUi.setup(swaggerDocument));

Este código sirve a nuestra documentación de Swagger en /api-docs. El archivo swagger.json es donde definiremos la estructura de nuestra API.

En nuestro archivo swagger.json, podemos agregar el siguiente código:

{
    "openapi": "3.0.0",
    "información": {
        "título": "API de recursos",
        "versión": "1.0.0",
        "description": "API para gestionar recursos"
    },
    "caminos": {
        "/": {
            "conseguir": {
                "summary": "Obtener todos los recursos",
                "respuestas": {
                    "200": {
                        "description": "Una lista de recursos"
                    }
                }
            },
            "correo": {
                "summary": "Crear un nuevo recurso",
                "respuestas": {
                    "200": {
                        "description": "El recurso creado"
                    }
                }
            }
        },
        "/{identificación}": {
            "conseguir":{
                "summary": "Obtener un recurso específico",
                "respuestas": {
                    "200": {
                        "description": "El recurso solicitado"
                    }
                }
            },
            "poner": {
                "summary": "Actualizar un recurso específico",
                "respuestas": {
                    "200": {
                        "description": "El recurso actualizado"
                    }
                }
            },
            "borrar": {
                "summary": "Eliminar un recurso específico",
                "respuestas": {
                    "200": {
                        "description": "Confirmación de eliminación"
                    }
                }
            }
        }
    }
}

Este código define la estructura de nuestra API, incluidas todas las operaciones CRUD que implementamos. Proporciona una descripción y un resumen de cada operación, así como posibles códigos de respuesta.

Con eso, tenemos una API CRUD completa con NodeJS y MongoDB, junto con su documentación. Esto hará que sea mucho más fácil para otros desarrolladores utilizar nuestra API.