Geração Swagger/OpenAPI para Node.js (JavaScript): ferramentas e exemplos

Geração Swagger/OpenAPI para Node.js (JavaScript)

No desenvolvimento de aplicações web modernas em Node.js, uma das tarefas principais é criar uma documentação clara e atualizada para a API. Swagger (OpenAPI) é um padrão para descrever interfaces RESTful que permite gerar automaticamente documentação interativa, testar requisições e manter contratos entre cliente e servidor. Neste artigo, vamos abordar como configurar a geração de documentação Swagger/OpenAPI para aplicações Node.js usando bibliotecas populares.

O que são Swagger e OpenAPI?

OpenAPI Specification (anteriormente conhecida como Swagger Specification) é um padrão formal para descrever APIs HTTP. Ela permite:

• Definir endpoints, métodos, parâmetros e tipos de resposta.
• Gerar automaticamente SDKs para clientes.
• Criar documentação interativa (Swagger UI).
• Validar requisições e respostas.

Para Node.js, existem várias bibliotecas que facilitam a integração com OpenAPI. Vamos analisar as duas mais populares: swagger-jsdoc e swagger-ui-express.

Bibliotecas para geração Swagger em Node.js

As principais ferramentas:

• swagger-jsdoc — analisa comentários JSDoc no código e monta a especificação OpenAPI a partir deles.
• swagger-ui-express — exibe a especificação gerada como uma página web interativa.
• @nestjs/swagger (se você usa NestJS) — decoradores para geração automática.

Vamos focar na combinação swagger-jsdoc + swagger-ui-express para Express.js.

Instalação e configuração

Instale os pacotes necessários via npm:

npm install swagger-jsdoc swagger-ui-express

Crie um arquivo swagger.js com a configuração básica:

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

const options = {    definition: {        openapi: '3.0.0',        info: {            title: 'Minha API Node.js',            version: '1.0.0',            description: 'Exemplo de API com geração automática Swagger',        },        servers: [            { url: 'http://localhost:3000' },        ],    },    apis: ['./routes/*.js'], // caminho para os arquivos com endpoints};

const swaggerSpec = swaggerJsdoc(options);

module.exports = { swaggerUi, swaggerSpec };

Adicionando comentários JSDoc aos endpoints

Agora, nos seus arquivos de rotas (por exemplo, routes/users.js), adicione comentários no formato OpenAPI:

/** * @openapi * /users: *   get: *     summary: Obter lista de usuários *     tags: [Users] *     parameters: *       - in: query *         name: limit *         schema: *           type: integer *         description: Número de usuários (padrão 10) *     responses: *       200: *         description: Lista de usuários *         content: *           application/json: *             schema: *               type: array *               items: *                 $ref: '#/components/schemas/User' */router.get('/users', async (req, res) => {    const users = await getUsers(req.query.limit || 10);    res.json(users);});

Defina também o modelo de dados:

/** * @openapi * components: *   schemas: *     User: *       type: object *       properties: *         id: *           type: integer *         name: *           type: string *         email: *           type: string */

Conectando Swagger UI ao Express

No arquivo principal da aplicação (app.js ou index.js), adicione:

const express = require('express');const { swaggerUi,