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

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

Ao desenvolver uma REST API em Node.js, uma das tarefas principais é criar uma documentação clara e atualizada. Swagger (agora OpenAPI) tornou-se o padrão de facto para descrever APIs. Neste artigo, analisaremos as principais ferramentas para geração automática de especificações OpenAPI em projetos JavaScript (Node.js).

O que é OpenAPI e por que gerá-lo?

OpenAPI é uma especificação para descrever APIs RESTful em formato JSON ou YAML. Ela permite:

• Criar automaticamente documentação interativa (Swagger UI)
• Gerar SDKs de cliente para diferentes linguagens
• Realizar validação de requisições e respostas
• Simplificar a integração entre equipes

Escrever a especificação manualmente é um processo trabalhoso que rapidamente se torna desatualizado. Por isso, para Node.js, foram desenvolvidas ferramentas que geram OpenAPI a partir do código.

Principais ferramentas para geração de OpenAPI em Node.js

1. swagger-jsdoc

A biblioteca mais popular, que analisa comentários JSDoc no código e os converte em uma especificação OpenAPI. Instala-se via npm:

npm install swagger-jsdoc swagger-ui-express

Exemplo de uso com Express:

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

const options = {  definition: {    openapi: '3.0.0',    info: {      title: 'Minha API',      version: '1.0.0',      description: 'Exemplo de API com geração de documentação'    },    servers: [      { url: 'http://localhost:3000' }    ]  },  apis: ['./routes/*.js'] // caminho para arquivos com anotações};

const swaggerSpec = swaggerJsdoc(options);app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// Exemplo de rota com anotação/** * @openapi * /users: *   get: *     summary: Obter lista de usuários *     tags: [Users] *     responses: *       200: *         description: Resposta bem-sucedida *         content: *           application/json: *             schema: *               type: array *               items: *                 $ref: '#/components/schemas/User' */app.get('/users', (req, res) => {  res.json([{ id: 1, name: 'Ivan' }]);});

app.listen(3000);

2. swagger-autogen

Uma alternativa mais moderna, que gera a especificação com base em anotações em comentários e determina automaticamente os tipos de dados. Instalação:

npm install swagger-autogen

Exemplo de script de geração:

const swaggerAutogen = require('swagger-autogen')();

const doc = {  info: {    title: 'Minha API',    description: 'Descrição da API'  },  host: 'localhost:3000',  schemes: ['http']};

const outputFile = './swagger-output.json';const endpointsFiles = ['./app.js']; // arquivo principal com rotas

swaggerAutogen(outputFile, endpointsFiles, doc).then(() => {  require('./app.js'); // iniciar servidor após geração});

Nas rotas, basta adicionar um comentário:

// #swagger.tags = ['Users']// #swagger.description = 'Endpoint para obter usuários'app.get('/users', (req, res) => {  // #swagger.responses[200] = { description: 'Lista de usuários' }  res.json([{ id: 1, name: 'Ana' }]);});

3. express-oas-generator

Uma biblioteca que intercepta requisições e constrói automaticamente a especificação OpenAPI com base nos dados reais. Adequada para protótipos:

npm install express-oas-generator

const express = require('express');const expressOasGenerator = require('express-oas-generator');const app = express();

expressOasGenerator.init(app, {}); // inicialização

app.get('/products', (req, res) => {  res.json