16.12. Criando um CRUD com NodeJS e MongoDB: Documentação da API

Uma das partes mais cruciais no desenvolvimento de uma API é a sua documentação. Uma API bem documentada é uma ferramenta poderosa para os desenvolvedores, pois facilita o seu uso e compreensão. Neste capítulo, vamos abordar como documentar uma API criada com NodeJS e MongoDB, focando em um CRUD (Create, Read, Update, Delete).

Começaremos criando uma nova rota em nossa aplicação NodeJS. Usaremos o Express, um framework popular para NodeJS, para criar nossas rotas. Nossa rota será responsável por lidar com todas as operações CRUD para um recurso específico. Usaremos o MongoDB, um banco de dados NoSQL, para armazenar nossos dados.

Primeiro, vamos definir nossa rota. Em nosso arquivo de rotas, adicionamos o seguinte código:

const express = require('express');
const router = express.Router();
const ResourceController = require('../controllers/resourceController');

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

module.exports = router;

Este código define uma nova rota que lida com todas as operações CRUD para um recurso. O ResourceController é um controlador que nós criaremos em breve, que lidará com a lógica para cada operação.

Agora vamos criar nosso controlador. Em um novo arquivo, adicione o seguinte código:

const Resource = require('../models/resource');

exports.getAll = async (req, res) => {
    const resources = await Resource.find();
    res.json(resources);
};

exports.create = async (req, res) => {
    const newResource = new Resource(req.body);
    const resource = await newResource.save();
    res.json(resource);
};

exports.getOne = async (req, res) => {
    const resource = await Resource.findById(req.params.id);
    res.json(resource);
};

exports.update = async (req, res) => {
    const resource = await Resource.findByIdAndUpdate(req.params.id, req.body, {new: true});
    res.json(resource);
};

exports.delete = async (req, res) => {
    await Resource.findByIdAndRemove(req.params.id);
    res.json({message: 'Resource deleted'});
};

Este código define um controlador que lida com todas as operações CRUD para um recurso. Ele usa o modelo Resource que nós criaremos em breve para interagir com nosso banco de dados MongoDB.

Agora, vamos criar nosso modelo. Em um novo arquivo, adicione o seguinte código:

const mongoose = require('mongoose');

const ResourceSchema = new mongoose.Schema({
    name: {
        type: String,
        required: true
    },
    description: {
        type: String,
        required: true
    }
});

module.exports = mongoose.model('Resource', ResourceSchema);

Este código define um modelo para nossos recursos. Ele usa o Mongoose, uma biblioteca popular para MongoDB, para definir um esquema para nossos dados.

Agora que temos nossa API configurada, é hora de documentá-la. A documentação é crucial para garantir que outros desenvolvedores possam entender e usar nossa API corretamente. Existem várias ferramentas disponíveis para documentar APIs, mas uma das mais populares é o Swagger.

O Swagger é uma ferramenta de documentação de API que permite aos desenvolvedores definir a estrutura de sua API usando um formato de descrição de API. Ele gera uma interface de usuário interativa que permite aos desenvolvedores explorar e testar a API.

Para usar o Swagger, primeiro precisamos instalar o pacote swagger-ui-express:

npm install swagger-ui-express

Em seguida, podemos adicionar o seguinte código ao nosso arquivo de rotas:

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 serve nossa documentação Swagger em /api-docs. O arquivo swagger.json é onde definiremos a estrutura de nossa API.

Em nosso arquivo swagger.json, podemos adicionar o seguinte código:

{
    "openapi": "3.0.0",
    "info": {
        "title": "Resource API",
        "version": "1.0.0",
        "description": "API for managing resources"
    },
    "paths": {
        "/": {
            "get": {
                "summary": "Get all resources",
                "responses": {
                    "200": {
                        "description": "A list of resources"
                    }
                }
            },
            "post": {
                "summary": "Create a new resource",
                "responses": {
                    "200": {
                        "description": "The created resource"
                    }
                }
            }
        },
        "/{id}": {
            "get": {
                "summary": "Get a specific resource",
                "responses": {
                    "200": {
                        "description": "The requested resource"
                    }
                }
            },
            "put": {
                "summary": "Update a specific resource",
                "responses": {
                    "200": {
                        "description": "The updated resource"
                    }
                }
            },
            "delete": {
                "summary": "Delete a specific resource",
                "responses": {
                    "200": {
                        "description": "Confirmation of deletion"
                    }
                }
            }
        }
    }
}

Este código define a estrutura de nossa API, incluindo todas as operações CRUD que implementamos. Ele fornece uma descrição e um resumo para cada operação, bem como os possíveis códigos de resposta.

Com isso, temos uma API CRUD completa com NodeJS e MongoDB, juntamente com sua documentação. Isso facilitará muito o uso de nossa API por outros desenvolvedores.