Introdução (3 min)

Prezados futuros arquitetos de sistemas, sejam bem-vindos à Aula 78, onde desvendaremos um pilar fundamental no desenvolvimento e consumo de APIs modernas: a documentação com Swagger/OpenAPI 3.0.

Imagine que você está em um restaurante sofisticado. Antes mesmo de fazer seu pedido, você recebe um cardápio completo e detalhado. Ele descreve cada prato, seus ingredientes, o preço e até mesmo sugestões de acompanhamento. Sem ele, você estaria perdido, tentando adivinhar o que pedir ou como combinar os sabores.

No universo das APIs, a documentação OpenAPI funciona exatamente como esse cardápio. Ela é a planta arquitetônica ou o manual de instruções definitivo da sua API. Detalha todos os endpoints disponíveis, os métodos HTTP aceitos, os parâmetros esperados, os formatos dos dados de entrada e saída, e até mesmo os possíveis códigos de erro. É o guia que habilita desenvolvedores, sejam eles da sua equipe ou externos, a entenderem e interagirem com sua API de forma eficiente e sem fricções.

A relevância da documentação para APIs modernas é inquestionável. Ela é decisiva para a colaboração entre equipes, o rápido onboarding de novos desenvolvedores, a automação de testes e até mesmo a geração de SDKs (kits de desenvolvimento de software) para diversas linguagens. Uma API bem documentada é uma API que convida ao uso e à integração, valorizando o seu trabalho e o de sua equipe.

Nesta aula avançada, vamos desenvolver um servidor Node.js com Express e, em seguida, integrar a documentação Swagger/OpenAPI 3.0 de forma prática e robusta. Você aprenderá a descrever seus endpoints de forma declarativa, a servir essa documentação interativa através de uma interface web e a garantir que ela esteja sempre alinhada com o seu código. No ecossistema Node.js/Express, isso significa elevar a maturidade do seu projeto, transformando-o em uma solução mais profissional e sustentável.

Conceito Fundamental (7 min)

Vamos mergulhar no âmago do que significa documentar uma API com Swagger e OpenAPI. Apesar de frequentemente usados como sinônimos, é crucial entender a distinção entre esses termos.

OpenAPI Specification (OAS)

A OpenAPI Specification (OAS) é uma especificação agnóstica de linguagem, padrão da indústria, para descrever APIs RESTful. É um formato de descrição de interface legível tanto por humanos quanto por máquinas. Ela permite que tanto pessoas quanto computadores descubram e compreendam os recursos de um serviço sem a necessidade de acessar o código-fonte, a documentação ou inspecionar o tráfego da rede. A OAS é o formato padronizado para o “cardápio” da sua API, geralmente escrito em YAML ou JSON.

Cada versão da OAS aprimora a forma como as APIs podem ser descritas. A OpenAPI 3.0, em particular, trouxe melhorias significativas na estrutura, na capacidade de reuso de componentes e na expressividade para descrever cenários complexos, como múltiplos servidores, diferentes tipos de segurança e callbacks.

Swagger

O termo Swagger, por sua vez, refere-se a um conjunto de ferramentas de código aberto que foram construídas em torno da OpenAPI Specification. As principais ferramentas do ecossistema Swagger incluem:

Swagger UI: Uma ferramenta que renderiza a descrição de uma API OpenAPI em uma interface de usuário interativa e amigável no navegador, permitindo que os desenvolvedores visualizem e testem endpoints diretamente. É o “display do cardápio”.
Swagger Editor: Um editor baseado em navegador para escrever e validar descrições de API OpenAPI em tempo real.
Swagger Codegen: Uma ferramenta que gera automaticamente código-fonte (SDKs de cliente, stubs de servidor) a partir de uma descrição OpenAPI.

Portanto, a OpenAPI é a especificação, o documento padrão, enquanto o Swagger é o conjunto de ferramentas que nos ajuda a criar, visualizar e consumir essa especificação.

Terminologia da Indústria

Ao trabalhar com OpenAPI, você encontrará alguns termos fundamentais:

Paths (Caminhos): Representam os endpoints individuais da sua API (ex: /usuarios, /produtos/{id}).
Operations (Operações): Os métodos HTTP (GET, POST, PUT, DELETE) associados a cada path. Cada operação pode ter uma descrição, parâmetros e respostas.
Parameters (Parâmetros): Dados enviados em uma requisição, que podem ser de quatro tipos: query (na URL), header (cabeçalho da requisição), path (parte da URL) ou cookie.
Schemas (Esquemas): Descrevem a estrutura dos dados para requisições e respostas. Utilizam o padrão JSON Schema e são cruciais para a validação.
Components (Componentes): Uma seção da especificação OpenAPI que permite definir estruturas de dados, parâmetros, cabeçalhos, respostas e esquemas de segurança reutilizáveis. Isso é vital para evitar repetição e manter a consistência.

Casos de Uso Reais em Produção

A documentação OpenAPI é valiosíssima em diversos cenários:

Integração de Equipes: Equipes de front-end, mobile e back-end podem desenvolver em paralelo, confiando na especificação da API.
APIs Públicas: Empresas como Stripe, Twilio e GitHub utilizam descrições semelhantes para facilitar a integração por desenvolvedores externos.
Geração Automática de Clientes: Ferramentas podem consumir a especificação para gerar automaticamente bibliotecas de cliente em várias linguagens, economizando tempo e reduzindo erros.
Testes Automatizados: A descrição da API pode ser usada para gerar automaticamente casos de teste, garantindo a conformidade da implementação com a especificação.

Integração com Outras Tecnologias

No contexto do Node.js e Express, a integração é facilitada por middlewares como swagger-ui-express, que serve a interface interativa do Swagger UI, e bibliotecas como yamljs para carregar descrições em YAML. Em ambientes de CI/CD (Continuous Integration/Continuous Delivery), ferramentas podem validar a documentação OpenAPI em cada deploy, ou até mesmo compará-la com o código-fonte para identificar inconsistências.

Vantagens e Desvantagens

Vantagens:

Clareza e Consistência: Garante que todos os envolvidos tenham uma compreensão unificada da API.
Auto-descrição: A API se torna auto-explicativa.
Produtividade Aumentada: Facilita o consumo da API e acelera o desenvolvimento de clientes.
Qualidade Assegurada: Habilita a validação de requisições e respostas, e a geração de testes.
Colaboração Aprimorada: Reduz a necessidade de comunicação constante sobre detalhes da API.

Desvantagens:

Custo Inicial de Implementação: Exige um esforço inicial para desenvolver e manter a especificação.
Risco de Desalinhamento (Drift): Se não houver disciplina ou automação, a documentação pode se desalinhar do código real da API.
Complexidade para APIS Pequenas: Pode ser um “overkill” para APIs muito simples com poucos endpoints.

Apesar das desvantagens, os benefícios a longo prazo para projetos enterprise são esmagadores, tornando a adoção do OpenAPI uma prática fundamental para qualquer equipe séria de desenvolvimento de APIs.

Implementação Prática (10 min)

Vamos agora construir nossa aplicação Node.js/Express e integrar a documentação Swagger/OpenAPI 3.0. Nosso objetivo é criar uma API simples de gerenciamento de tarefas e documentá-la de forma exemplar.

Passo 1: Configuração Inicial do Projeto

Crie um novo diretório para o seu projeto e inicialize-o:

mkdir api-docs-aula
cd api-docs-aula
npm init -y

Instale as dependências essenciais:

npm install express swagger-ui-express yamljs

express: Nosso framework web para construir a API.
swagger-ui-express: Middleware para servir a interface interativa do Swagger UI.
yamljs: Biblioteca para carregar arquivos YAML de forma simples.

Passo 2: Definindo a Especificação OpenAPI em YAML

Crie um arquivo chamado openapi.yaml na raiz do seu projeto. Este arquivo será o “cardápio” da sua API.

# openapi.yaml
openapi: 3.0.0
info:
  title: API de Tarefas - Aula 78
  description: Uma API de exemplo para gerenciamento de tarefas, documentada com OpenAPI 3.0.
  version: 1.0.0
servers:
  - url: http://localhost:3000/api/v1 # URL base da sua API
    description: Servidor de Desenvolvimento Local
  - url: https://sua-url-hostgator.com.br/api/v1 # Exemplo para HostGator Plano M
    description: Servidor de Produção (HostGator Plano M)
tags:
  - name: Tarefas
    description: Operações relacionadas a tarefas
paths:
  /tarefas:
    get:
      summary: Lista todas as tarefas
      description: Retorna uma lista de todas as tarefas cadastradas no sistema.
      tags:
        - Tarefas
      responses:
        '200':
          description: Uma lista de tarefas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tarefa'
        '500':
          description: Erro interno do servidor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Cria uma nova tarefa
      description: Adiciona uma nova tarefa à lista.
      tags:
        - Tarefas
      requestBody:
        description: Objeto de tarefa a ser criado.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NovaTarefa'
      responses:
        '201':
          description: Tarefa criada com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tarefa'
        '400':
          description: Dados de entrada inválidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Erro interno do servidor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /tarefas/{id}:
    get:
      summary: Obtém uma tarefa por ID
      description: Retorna uma única tarefa baseada no ID fornecido.
      tags:
        - Tarefas
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID da tarefa a ser buscada.
      responses:
        '200':
          description: Uma tarefa específica.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tarefa'
        '404':
          description: Tarefa não encontrada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Erro interno do servidor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Tarefa:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: O identificador único da tarefa.
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        titulo:
          type: string
          description: O título da tarefa.
          example: Estudar OpenAPI 3.0
        concluida:
          type: boolean
          description: Indica se a tarefa foi concluída.
          example: false
      required:
        - id
        - titulo
        - concluida
    NovaTarefa:
      type: object
      properties:
        titulo:
          type: string
          description: O título da nova tarefa.
          example: Preparar café
      required:
        - titulo
    ErrorResponse:
      type: object
      properties:
        codigo:
          type: string
          example: "ERRO_INTERNO"
        mensagem:
          type: string
          example: "Ocorreu um erro inesperado no servidor."
      required:
        - codigo
        - mensagem

Comentários detalhados linha por linha do openapi.yaml:

openapi: 3.0.0: Declara a versão da especificação OpenAPI que estamos utilizando, vital para o parser.
info: Contém metadados sobre a API.
- title: O nome da sua API, que será exibido no Swagger UI.
- description: Uma descrição mais longa, explicando o propósito da API.
- version: A versão da sua API (ex: 1.0.0).

servers: Define os URLs base para sua API. Isso é particularmente valioso para ambientes diferentes (desenvolvimento, produção).
- Configurações específicas para HostGator Plano M: O segundo servidor (https://sua-url-hostgator.com.br/api/v1) mostra como você declararia a URL de produção. No HostGator, seu aplicativo Node.js geralmente roda em um processo PM2 ou similar e é acessado via um proxy reverso (como Nginx) que mapeia um subdomínio ou caminho da sua URL pública para a porta interna do seu aplicativo. Certifique-se de que a URL base aqui reflita o caminho que os clientes usarão para acessar sua API publicamente.

tags: Usado para agrupar endpoints relacionados no Swagger UI, facilitando a navegação.
paths: Aqui é onde você descreve cada endpoint (caminho) da sua API.
- /tarefas: O caminho para o recurso de tarefas.
- get: Define a operação GET para /tarefas.
  - summary: Breve descrição do que a operação faz.
  - description: Descrição mais detalhada.
  - tags: Associa esta operação à tag “Tarefas”.
  - responses: Descreve os possíveis retornos da operação.
    - '200': Resposta de sucesso.
      - description: Detalha a resposta.
      - content: Especifica o tipo de mídia (application/json).
      - schema: Define a estrutura dos dados retornados, referenciando um esquema reutilizável ($ref).

post: Define a operação POST para /tarefas.
- requestBody: Descreve o corpo da requisição POST.
  - required: true: Indica que o corpo da requisição é obrigatório.
  - content: Define o tipo de mídia e o esquema do corpo da requisição.

'201', '400', '500': Exemplos de respostas para criação e erros de validação/servidor.

/tarefas/{id}: Caminho com um parâmetro de path.
parameters: Define os parâmetros esperados para a operação.
- in: path: Indica que o parâmetro está na URL.
- name: id: O nome do parâmetro.
- schema: type: string: O tipo de dado do parâmetro.
- required: true: O parâmetro é obrigatório.

components: Seção para definir objetos reutilizáveis, uma prática enterprise essencial.
- schemas: Contém as definições de modelos de dados.
  - Tarefa: Define a estrutura de um objeto tarefa completo.
    - type: object, properties, required: Padrões JSON Schema para descrever a estrutura.
    - example: Um exemplo de valor para cada propriedade, extremamente útil para quem consome a API.

Passo 3: Criando o Servidor Express e Integrando o Swagger UI

Crie um arquivo chamado server.js (ou app.js) na raiz do seu projeto:

// server.js
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs'); // Para carregar nosso arquivo YAML
const path = require('path');
const { v4: uuidv4 } = require('uuid'); // Para gerar IDs únicos para tarefas
// Carrega o arquivo OpenAPI YAML
const swaggerDocument = YAML.load(path.join(__dirname, './openapi.yaml'));
const app = express();
const PORT = process.env.PORT || 3000; // Padrão enterprise: use a porta do ambiente ou 3000
// Middleware para parsear JSON no corpo da requisição
app.use(express.json());
// --- Rotas da API de Tarefas ---
let tarefas = [
  { id: uuidv4(), titulo: 'Estudar NodeJS', concluida: false },
  { id: uuidv4(), titulo: 'Preparar Aula 78', concluida: true },
];
// Logging profissional: Um middleware simples para registrar requisições
app.use((req, res, next) => {
  console.log([${new Date().toISOString()}] ${req.method} ${req.url});
  next();
});
// GET /api/v1/tarefas - Lista todas as tarefas
app.get('/api/v1/tarefas', (req, res) => {
  res.status(200).json(tarefas);
});
// GET /api/v1/tarefas/{id} - Obtém uma tarefa por ID
app.get('/api/v1/tarefas/:id', (req, res) => {
  const { id } = req.params;
  const tarefa = tarefas.find(t => t.id === id);
  if (!tarefa) {
    // Error handling eficiente: Tarefa não encontrada
    return res.status(404).json({
      codigo: 'TAREFA_NAO_ENCONTRADA',
      mensagem: Tarefa com ID '${id}' não encontrada.
    });
  }
  res.status(200).json(tarefa);
});
// POST /api/v1/tarefas - Cria uma nova tarefa
app.post('/api/v1/tarefas', (req, res) => {
  const { titulo } = req.body;
  // Validação de entrada robusta
  if (!titulo || typeof titulo !== 'string' || titulo.trim().length === 0) {
    return res.status(400).json({
      codigo: 'TITULO_INVALIDO',
      mensagem: 'O título da tarefa é obrigatório e deve ser uma string não vazia.'
    });
  }
  const novaTarefa = {
    id: uuidv4(),
    titulo: titulo.trim(),
    concluida: false,
  };
  tarefas.push(novaTarefa);
  res.status(201).json(novaTarefa);
});
// --- Configuração da Documentação Swagger/OpenAPI ---
// Serve a documentação Swagger UI na rota /api-docs
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
// Rota padrão para caso não encontre nenhuma das rotas anteriores
app.use((req, res, next) => {
  res.status(404).json({
    codigo: 'ROTA_NAO_ENCONTRADA',
    mensagem: A rota '${req.originalUrl}' não foi encontrada neste servidor.
  });
});
// Middleware de tratamento de erro genérico (500 Internal Server Error)
app.use((err, req, res, next) => {
  console.error(err.stack); // Loga o erro completo no console do servidor
  res.status(500).json({
    codigo: 'ERRO_INTERNO_SERVIDOR',
    mensagem: 'Ocorreu um erro inesperado no servidor. Por favor, tente novamente mais tarde.'
  });
});
// Inicia o servidor
app.listen(PORT, () => {
  console.log(Servidor Express rodando na porta ${PORT});
  console.log(Documentação Swagger UI disponível em http://localhost:${PORT}/api-docs);
});

Comentários detalhados linha por linha do server.js:

const express = require('express');: Importa o módulo Express.
const swaggerUi = require('swagger-ui-express');: Importa o middleware do Swagger UI.
const YAML = require('yamljs');: Importa a biblioteca para carregar arquivos YAML.
const path = require('path');: Módulo nativo do Node.js para manipulação de caminhos de arquivos.
const { v4: uuidv4 } = require('uuid');: Importa uma função para gerar IDs universais únicos (UUIDs), importante para identificação de recursos.
const swaggerDocument = YAML.load(path.join(__dirname, './openapi.yaml'));: Carrega nosso arquivo openapi.yaml. path.join(__dirname, './openapi.yaml') garante que o caminho seja resolvido corretamente, independentemente de onde o script é executado.
const app = express();: Cria uma instância da aplicação Express.
const PORT = process.env.PORT || 3000;: Define a porta. process.env.PORT é um padrão enterprise para que o ambiente de hospedagem (como HostGator, Heroku, AWS) possa definir a porta, com 3000 como fallback local.
app.use(express.json());: Middleware para permitir que o Express entenda requisições com corpo JSON.
let tarefas = [...]: Um array simples para simular um banco de dados de tarefas.
app.use((req, res, next) => { ... });: Logging profissional. Um middleware simples para registrar cada requisição no console, útil para depuração e monitoramento.
app.get('/api/v1/tarefas', ...): Define a rota GET para listar todas as tarefas.
app.get('/api/v1/tarefas/:id', ...): Define a rota GET para obter uma tarefa por ID. Inclui error handling eficiente para o caso de a tarefa não ser encontrada, retornando um 404.
app.post('/api/v1/tarefas', ...): Define a rota POST para criar uma nova tarefa.
- Validação de entrada robusta: Verifica se o titulo existe e é uma string válida antes de criar a tarefa, retornando um 400 em caso de erro.

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));: Esta é a linha crucial para integrar o Swagger UI.
- /api-docs: A URL onde a documentação será acessível.
- swaggerUi.serve: Middleware que serve os arquivos estáticos do Swagger UI.
- swaggerUi.setup(swaggerDocument): Middleware que inicializa o Swagger UI com a nossa especificação OpenAPI carregada.

app.use((req, res, next) => { ... });: Um middleware para capturar rotas não encontradas (404 Not Found), garantindo uma resposta consistente.
app.use((err, req, res, next) => { ... });: Um middleware de tratamento de erro genérico. Ele captura quaisquer erros não tratados nas rotas e retorna um 500 Internal Server Error, enquanto loga o erro completo para investigação.
app.listen(PORT, ...): Inicia o servidor Express.

Testes Básicos e Configurações para HostGator Plano M

Para rodar localmente:

node server.js

Após iniciar o servidor, abra seu navegador e acesse:

http://localhost:3000/api/v1/tarefas para ver os dados da API.
http://localhost:3000/api-docs para acessar a interface interativa do Swagger UI.

Configuração para HostGator Plano M:

No HostGator, o Node.js geralmente é executado através de um processo como o PM2 ou um configurador de aplicação. A parte mais importante é que seu aplicativo ouça a porta que o ambiente HostGator irá fornecer (via process.env.PORT) e que as URLs da sua API e da documentação estejam corretas no openapi.yaml.

No server.js, já configuramos para usar process.env.PORT || 3000, o que é um padrão robusto. A URL no openapi.yaml deve ser o domínio ou subdomínio que você configurou no painel do HostGator para sua aplicação Node.js (ex: https://sua-url-hostgator.com.br/api/v1).

Observações:

Versionamento: Note o uso de /api/v1 nas rotas. Isso é uma prática recomendada para versionamento de API.
Modularização: Para projetos maiores, você separaria as definições de rotas e o openapi.yaml em módulos menores. Por exemplo, cada recurso (tarefas, usuários) poderia ter seu próprio arquivo YAML.
Alternativas: Embora tenhamos usado um arquivo YAML estático, existem bibliotecas (como express-jsdoc-swagger ou swagger-autogen) que geram a especificação dinamicamente a partir de comentários JSDoc no seu código ou analisando suas rotas. Para um nível avançado, a manutenção manual do YAML permite maior controle e expressividade.

Exercício Hands-On (5 min)

Agora é a sua vez de colocar a mão na massa e expandir nossa API e documentação.

Desafio Prático

Adicione um novo endpoint PUT para atualizar o status de uma tarefa (marcar como concluída ou não concluída) e documente-o completamente no openapi.yaml. A rota deve ser PUT /api/v1/tarefas/{id}/concluir e deve aceitar um corpo JSON com {"concluida": true/false}.

Solução Detalhada Passo a Passo

Passo 1: Modificar o server.js para adicionar o endpoint PUT

Adicione o seguinte código ao seu arquivo server.js, após a rota POST:

// PUT /api/v1/tarefas/{id}/concluir - Atualiza o status de conclusão de uma tarefa
app.put('/api/v1/tarefas/:id/concluir', (req, res) => {
  const { id } = req.params;
  const { concluida } = req.body;
  // Validação de entrada robusta
  if (typeof concluida !== 'boolean') {
    return res.status(400).json({
      codigo: 'STATUS_INVALIDO',
      mensagem: 'O campo "concluida" é obrigatório e deve ser um booleano (true ou false).'
    });
  }
  const index = tarefas.findIndex(t => t.id === id);
  if (index === -1) {
    return res.status(404).json({
      codigo: 'TAREFA_NAO_ENCONTRADA',
      mensagem: Tarefa com ID '${id}' não encontrada.
    });
  }
  tarefas[index].concluida = concluida;
  res.status(200).json(tarefas[index]);
});

Passo 2: Atualizar o openapi.yaml para documentar o novo endpoint

Adicione a seguinte seção de put dentro de /tarefas/{id} no seu openapi.yaml, logo abaixo da seção get para o mesmo path:

  /tarefas/{id}:
    get:
      # ... (código existente para GET)
    put: # Adicione esta seção
      summary: Atualiza o status de conclusão de uma tarefa
      description: Permite marcar uma tarefa como concluída ou não concluída.
      tags:
        - Tarefas
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: ID da tarefa a ser atualizada.
      requestBody:
        description: Novo status de conclusão da tarefa.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                concluida:
                  type: boolean
                  description: O novo status de conclusão da tarefa.
                  example: true
              required:
                - concluida
      responses:
        '200':
          description: Tarefa atualizada com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tarefa'
        '400':
          description: Dados de entrada inválidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Tarefa não encontrada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Erro interno do servidor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

Note que para o endpoint PUT, o parâmetro id é do tipo path e o corpo da requisição (requestBody) espera um objeto JSON com a propriedade concluida do tipo booleano.

Passo 3: Reiniciar o Servidor

Salve ambos os arquivos (server.js e openapi.yaml) e reinicie seu servidor Node.js:

node server.js

Como Testar e Validar o Resultado

Abra seu navegador e acesse a documentação do Swagger UI: http://localhost:3000/api-docs.
Role para baixo até a seção “Tarefas”. Você deverá ver o novo endpoint PUT /api/v1/tarefas/{id}/concluir listado.
Teste a documentação: Clique no endpoint PUT. A interface mostrará os parâmetros de path (id), o corpo da requisição esperado (concluida: boolean) e as possíveis respostas.
Execute o endpoint:
1. Primeiro, use o endpoint GET /api/v1/tarefas para obter o ID de uma tarefa existente.
2. No endpoint PUT, clique em “Try it out”.
3. Insira um ID de tarefa válido no campo id (ex: d290f1ee-6c54-4b01-90e6-d701748f0851).
4. No campo “Request body”, insira {"concluida": true} ou {"concluida": false}.
5. Clique em “Execute”.
6. Verifique a resposta (deve ser 200 OK com a tarefa atualizada).

Valide a atualização: Use novamente o endpoint GET /api/v1/tarefas/{id} (com o mesmo ID) ou GET /api/v1/tarefas para confirmar que o status da tarefa foi alterado.

Troubleshooting dos Erros Mais Comuns

Erro de Análise YAML (YAML Parsing Error): Geralmente ocorre devido a problemas de indentação ou sintaxe no seu openapi.yaml. O YAML é sensível a espaços. Use um editor que suporte realce de sintaxe YAML e validação, ou uma ferramenta online como codebeautify.org/yaml-validator.
Endpoint Não Aparece no Swagger UI: Verifique se o caminho no openapi.yaml está correto e alinhado com o caminho no Express (ex: /tarefas/{id} no YAML corresponde a /tarefas/:id no Express). Certifique-se de que o swaggerDocument está sendo carregado corretamente em server.js.
Requisições de Teste Falham no Swagger UI: Verifique se os servers no openapi.yaml estão apontando para o URL correto da sua API (ex: http://localhost:3000/api/v1). Se a API estiver em um caminho diferente, ajuste o url do servidor.
Erro 404 para o Swagger UI: Certifique-se de que app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); está configurado corretamente e que você está acessando a URL correta (/api-docs).

Próximos Passos Sugeridos

Para aprofundar ainda mais seu conhecimento e consolidar a prática:

Adicione Validações de Schema Automáticas: Explore bibliotecas como express-openapi-validator que podem validar automaticamente requisições de entrada e respostas de saída contra sua especificação OpenAPI, garantindo que sua API sempre esteja em conformidade com sua documentação.
Implemente Segurança: Adicione esquemas de segurança (como autenticação JWT ou API Key) ao seu openapi.yaml e configure o Swagger UI para permitir testes com tokens de autenticação.
Explore Ferramentas de Geração de Código: Experimente o Swagger Codegen para gerar automaticamente SDKs de cliente para sua API em diferentes linguagens de programação, ou stubs de servidor.
Integre em um Pipeline de CI/CD: Configure seu pipeline para validar automaticamente o openapi.yaml em cada commit ou deploy, garantindo que a documentação esteja sempre atualizada e livre de erros de sintaxe.
Componentes Reutilizáveis: Crie mais componentes para parâmetros, cabeçalhos e respostas de erro comuns para reduzir a duplicação no seu openapi.yaml.

Dominar a documentação OpenAPI/Swagger é uma habilidade que eleva drasticamente a qualidade e a usabilidade das suas APIs, posicionando você como um desenvolvedor de destaque no mercado.

🚀 Pronto para a próxima aula?

Continue sua jornada no desenvolvimento de APIs e domine Node.js & Express!

📚 Ver todas as aulas

Leodario.com

Aula 78 – API JavaScript, Node.js e Express – API Documentation – Swagger/OpenAPI 3.0