Como documentar uma API Node.js usando Swagger?

O Swagger é uma ferramenta que permite documentar APIs de forma interativa, facilitando a visualização e o teste dos endpoints. Com ele, podemos gerar documentação automaticamente no Node.js com Express.js.

1. Instalando Swagger no Node.js

Antes de começar, instale os pacotes necessários:

npm install swagger-ui-express swagger-jsdoc

2. Configurando Swagger no Express.js

Crie um arquivo swagger.js para definir a documentação da API:

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: 'Documentação da API usando Swagger',
        },
    },
    apis: ['./server.js'], // Arquivo onde as rotas são documentadas
};

const swaggerSpec = swaggerJsdoc(options);

module.exports = { swaggerUi, swaggerSpec };

3. Integrando Swagger ao servidor

No server.js, importe e adicione o Swagger:

const express = require('express');
const { swaggerUi, swaggerSpec } = require('./swagger');

const app = express();
app.use(express.json());

// Rota para acessar a documentação
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

app.listen(3000, () => console.log('Servidor rodando na porta 3000'));

Agora, podemos acessar http://localhost:3000/api-docs para visualizar e testar os endpoints.

4. Documentando rotas com Swagger

No arquivo server.js, adicione anotações nos endpoints:

/**
 * @swagger
 * /ping:
 *   get:
 *     summary: Testa a API
 *     description: Retorna uma resposta simples
 *     responses:
 *       200:
 *         description: API respondendo normalmente
 */
app.get('/ping', (req, res) => {
    res.json({ mensagem: 'pong' });
});

Agora, o Swagger irá exibir esse endpoint na interface.

Conclusão

O Swagger facilita a documentação e testes de APIs Node.js, tornando a integração com clientes e desenvolvedores mais intuitiva e prática.

Por que documentar APIs com Swagger é essencial?

A documentação de APIs é fundamental para o desenvolvimento moderno. Empresas como Google, Stripe e Twitter usam o Swagger para criar documentação interativa, ajudando desenvolvedores a consumir suas APIs corretamente.

Com o Swagger, podemos testar endpoints sem precisar de ferramentas externas, além de gerar especificações padronizadas para integração com outros serviços.

Algumas aplicações:

Criação de documentação interativa
Facilidade na integração com clientes
Teste rápido de endpoints
Padronização de APIs
Geração de especificações OpenAPI

Dicas para quem está começando

Use swagger-jsdoc para gerar documentação baseada em código.
Acesse /api-docs para visualizar a documentação.
Documente todas as rotas, incluindo parâmetros e respostas esperadas.
Evite descrições genéricas; detalhe cada endpoint.
Atualize a documentação sempre que a API for modificada.

Contribuições de Henrique Almeida

Como documentar uma API Node.js usando Swagger?