Introdução (3 min)

Imagine um restaurante sem cardápio. Confuso, não? Uma API sem documentação é exatamente isso. Impossível de usar sem adivinhação. Documentação é vital para APIs modernas, permitindo que desenvolvedores entendam e integrem seus serviços facilmente.

Nesta aula, construiremos documentação completa para uma API simples usando Swagger/OpenAPI 3.0, um padrão da indústria para descrever APIs RESTful. Veremos como integrar o Swagger com um servidor Express em Node.js, rodando perfeitamente em um ambiente como o HostGator Plano M.

Conceito Fundamental (7 min)

Swagger/OpenAPI 3.0 é uma especificação para descrever APIs em um formato legível por máquina (JSON ou YAML). Ele define a estrutura da API, incluindo endpoints, parâmetros, tipos de dados, códigos de resposta e muito mais. Essa descrição padronizada facilita a geração de documentação interativa, clientes de API e código servidor.

Em ambientes de produção, o Swagger é essencial para colaboração entre equipes, integração com gateways de API e automação de testes. Ele se integra com diversas tecnologias, como Postman, ferramentas de geração de código e frameworks de servidor.

A principal vantagem do Swagger é a clareza. Ele elimina ambiguidades e facilita a adoção da sua API. A desvantagem pode ser o tempo investido na configuração inicial, mas o retorno a longo prazo é inquestionável.

Implementação Prática (10 min)

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json'); // Arquivo de definição Swagger

const app = express();
const port = 3000;
// Configuração do Swagger
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
// Rota de exemplo
app.get('/saudacao', (req, res) => {
  console.log('Requisição recebida para /saudacao'); // Logging profissional
  res.send('Olá, mundo!');
});
// Error handling básico
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).send('Algo deu errado!');
});
app.listen(port, () => {
  console.log(Servidor rodando em http://localhost:${port});
});

// swagger.json
{
  "openapi": "3.0.0",
  "info": {
    "title": "API de Exemplo",
    "version": "1.0.0",
    "description": "Uma API simples para demonstração do Swagger."
  },
  "paths": {
    "/saudacao": {
      "get": {
        "summary": "Retorna uma saudação.",
        "responses": {
          "200": {
            "description": "Saudação bem-sucedida.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}

Este código configura um servidor Express básico com uma rota /saudacao. O mais importante é a integração do Swagger UI via swagger-ui-express, servindo a documentação a partir de swagger.json. Observe o error handling e o logging profissional.

Exercício Hands-On (5 min)

Adicione uma nova rota /usuario que aceite um parâmetro nome na query string e retorne uma saudação personalizada. Documente essa nova rota no arquivo swagger.json, especificando o parâmetro, o tipo de dado e a resposta esperada. Teste a nova rota e a documentação atualizada no Swagger UI.

Solução:

Adicione a seguinte rota ao seu código e atualize o swagger.json conforme necessário.

app.get('/usuario', (req, res) => {
  const nome = req.query.nome || 'Visitante'; // Validação de entrada
  console.log(Requisição recebida para /usuario com nome: ${nome});
  res.send(Olá, ${nome}!);
});

Para testar, acesse /api-docs no seu navegador e interaja com a documentação. Experimente diferentes valores para o parâmetro nome.

Próximos passos: explore outras funcionalidades do Swagger, como autenticação, modelos de dados e geração de código cliente. Com o Swagger dominado, suas APIs serão mais acessíveis, robustas e prontas para o mundo!