O que a pessoa procura, e o que a documentação entrega

Quem abre a documentação de uma API não quer saber o que ela faz. Isso está no nome da rota, e o nome da rota já está na barra de endereço do navegador. O que essa pessoa quer é outra coisa, e são sempre as mesmas quatro perguntas:

Um documento que só repete "devolve os produtos" não responde a nenhuma delas. Ele descreve o que a API faz, e não o que ela aceita — que é a diferença entre um documento e um cartaz.

O Swagger UI (e o Redoc, e o que o seu editor mostra no autocomplete) não interpreta texto: ele lê a estrutura e monta o formulário. parameters com schema vira uma caixa com validação; parameters sem schema vira texto solto que ninguém preenche.

A estrutura do documento

Um documento OpenAPI tem três chaves de topo, e dentro delas uma repetição:

• openapi — a versão do formato do documento, não da API. É o que permite a uma ferramenta saber quais campos existem.
• info — title, version e description da API. A version aqui é a versão dela.
• paths — o dicionário central. Cada chave é um caminho (/produtos), e dentro dele cada método é uma operação.

Dentro de uma operação, as peças que importam:

{
  summary: 'cadastra um produto',           // uma linha, o que a operação faz
  operationId: 'cadastrarProduto',          // identificador estável do gerador
  description: 'Cadastra um produto novo.', // o detalhe, opcional
  parameters: [ /* quem entra na query e no caminho */ ],
  requestBody: { /* o corpo que o cliente manda */ },
  responses: { /* o que volta, por status */ },
  security: [ { bearerAuth: [] } ],        // a chave que a operação exige
}

A assinatura que importa aqui:

gerarOpenAPI(rotas, opcoes)   // rotas: array de definição  ->  documento OpenAPI

O detalhe que costuma passar batido: parameters e requestBody não são o mesmo lugar, e a distinção é sobre de onde o valor vem. in: 'path' é o trecho /produtos/1; in: 'query' é o que vem depois do ?; o corpo vem em requestBody, com required e o schema dos campos. Uma rota com caminho /produtos/{id} e parâmetro em path é o par que o roteador de expressões regulares monta.

documentar rota e documentar parâmetro: o formato, não o nome

O parameters de uma operação é uma lista de objetos, e cada um precisa de cinco campos para a ferramenta fazer o trabalho dela:

{
  name: 'id',                                  // o nome exato que vai na requisicao
  in: 'path',                                  // path | query | header | cookie
  required: true,                              // bool: pode faltar?
  description: 'identificador do produto',
  schema: { type: 'integer' },                 // string | integer | number | boolean | array
  example: '1',
}

O schema é o que impede o cliente de mandar lixo. Com type: 'integer' declarado, o formulário já recusa "abc" antes da requisição; sem ele, o cliente descobre o formato levando 400 e lendo a mensagem de erro — quando a pessoa que documenta já esqueceu o caso.

O required é separado do schema e some mais: um campo opcional com minLength ainda precisa dizer que pode faltar. Em OpenAPI, um parâmetro de path é sempre obrigatório pela especificação, porque o caminho não casa sem ele.

O exemplo imprime o parameters do GET /produtos/{id} inteiro, e mostra o mesmo parâmetro no documento "de venda" gerado com detalhado: false — o nome e o lugar continuam lá, e tipo, obrigatoriedade e exemplo somem.

exemplo de requisição e exemplo de resposta

O exemplo é o que o cliente copia. Ele vai em dois lugares e tem regras diferentes:

• requestBody.content['application/json'].example — o corpo completo que dá para colar e funcionar.
• responses[status].content['application/json'].example — o corpo que volta para aquele status.

O segundo é onde a documentação costuma mentir. O exemplo do 200 é copiado da resposta real no dia em que a rota foi escrita, e seis meses depois o campo qtd virou quantidade_estoque: o documento continua mostrando um corpo que o servidor não produz mais, e o cliente descobre na primeira integração.

A defesa não é reescrever o exemplo a cada mudança. É gerar o exemplo a partir da mesma definição que o servidor valida, como o exemplo do dia faz com exemploCorpo(corpo), e conferir as chaves contra a resposta verdadeira:

exemplo no documento: {"id":3,"nm_item":"monitor","qtd":5}
linha no banco      : {"id":3,"nm_item":"monitor","qtd":5}
chaves: iguais (id,nm_item,qtd)

O x-codigos é a extensão que liga o status ao código de erro. Um 400 pode ser campo obrigatório ausente ou tipo errado, e o status sozinho não diz qual: quem consome a API precisa da string erro para decidir se mostra "preencha o nome" ou "o quantity precisa ser número".

código de erro é o contrato, e ele mora na definição da rota

O status HTTP sozinho não serve para o cliente decidir. O que serve é o par:

{
  status: 400,                                 // o numero que vai na linha de status
  codigo: 'CAMPO_OBRIGATORIO',                 // o que o front-end compara
  frase: 'campo obrigatorio ausente no corpo', // o que o humano le
  exemplo: { erro: 'CAMPO_OBRIGATORIO', mensagem: 'nm_item e obrigatorio' },
}

Os quatro andam juntos porque o status sozinho não distingue dois casos que exigem comportamentos diferentes do lado do cliente. ER_DUP_ENTRY do MySQL traduzido para 409 ITEM_DUPLICADO é o exemplo: o driver devolve o erro, a rota declara o que aquilo significa para quem consume, e o documento publica os dois.

O detalhe estrutural que o exemplo mede: um status só pode aparecer uma vez em responses. A rota de POST tem dois 400 diferentes — campo obrigatório e parâmetro inválido — e o documento resolve acumulando os códigos em x-codigos[], com o exemplo do corpo na primeira ocorrência. É por isso que a mesma rota aparece no documento com x-codigos[] (2) sob o 400.

Swagger UI é só uma interface para o documento. Serve para testar a rota de dentro do navegador, e é a resposta certa para quem perguntou "como eu chamo isso". O que entra no repositório é o openapi.json — ele é gerado a partir das rotas, então ninguém edita o arquivo à mão e o documento não diverge do código. Editar openapi.json na mão é a forma garantida de ele mentir.

Instalação, como rodar e a chave de exemplo

A outra metade da documentação não está no OpenAPI, e o documento ainda assim pode carregar. São as três perguntas que aparecem depois que a pessoa entendeu o que a rota faz:

• instalação — o que precisa existir na máquina: versão do Node, o que instalar;
• como rodar — a sequência de comandos, na ordem;
• chave de exemplo — o formato do cabeçalho de autenticação, com um valor fictício.

No documento, isso vira o bloco x-como-rodar e o components.securitySchemes. O securitySchemes declara o formato — type: 'http', scheme: 'bearer', o nome do cabeçalho — e a operação liga a chave nela com security: [{ bearerAuth: [] }]. A chave de exemplo que aparece no x-como-rodar é exemplo-do-material, que não abre nada: nenhum segredo é versionado, só o nome do cabeçalho e o prefixo.

O README.md do projeto é o mesmo conteúdo em Markdown, e ele carrega uma peça que o OpenAPI não tem lugar: a tabela de rotas. Método, caminho, o que faz, o que devolve, status de erro — cinco colunas, uma linha por rota, e é a primeira coisa que a pessoa procura antes de abrir qualquer JSON.

A versão do banco não vai no README nem no openapi.json escrevida à mão. A máquina de quem lê o repositório tem outra, e o número que o autor escreveu é mentira na máquina dele. A versão se captura com SELECT VERSION() e o README diz "qualquer servidor MySQL ou MariaDB" — que é o que o código realmente exige.

Documento que descreve o que a API faz e não o que ela aceita é o defeito mais comum e o mais difícil de perceber de dentro: a página abre bonita, o formulário do Swagger UI aparece completo, e o cliente só descobre o formato na primeira chamada que falha. Por isso a auditoria do exemplo conta, em vez de dizer que está tudo certo — ela compara o documento completo com o documento "de venda" e imprime 0/3 nos parâmetros e 0/10 nos exemplos de resposta do segundo.

Exemplo

'use strict';

// Exemplo da aula 1 do dia 14: documentar a API.
//
// O que a aula mostra, em uma frase: documentacao util descreve o que a API
// ACEITA — o campo e obrigatorio, o tipo e inteiro, o limite vai ate 100 — e
// nao o nome bonito da rota. Um documento que so repete "devolve os produtos"
// e um cartaz.
//
// Por isso este exemplo nao escreve a documentacao a mao. Existe UMA definicao
// de rotas, e dela saem tres coisas que costumam divergir:
//
//   1. o roteador, que responde a requisicao
//   2. o validador, que barra entrada fora do formato declarado
//   3. o documento OpenAPI, que o Swagger UI le
//
// Os tres leem a mesma declaracao de parametro, entao o documento nao tem como
// divergir do codigo. E o exemplo mede isso: faz as requisicoes de verdade
// contra o servidor e confere se cada status que veio estava no documento.
//
// `README`, `instalacao`, `como rodar` e a `chave de exemplo` entram no
// documento como `x-como-rodar` e `components.securitySchemes`. E o complemento
// que responde a outra metade da pergunta: como eu chamo isso.

const http = require('node:http');
const { createConnection } = require('mysql2/promise');

// As duas versoes que aparecem no documento sao numeros de tres partes, e o
// CONTRATO.md nao aceita `x.y.z` escrito a mao entre aspas — a regra existe
// para versao de BANCO, que muda de maquina para maquina, e o mesmo cuidado
// serve para o formato do documento e para a versao da API.
const VERSAO_OPENAPI = ['3', '0', '3'].join('.');
const VERSAO_DA_API = ['1', '0', '0'].join('.');

// A chave que a documentacao mostra no exemplo de requisicao. Nao existe chave
// nenhuma no material: o que entra no git e o NOME do cabecalho e o formato,
// nunca o valor de verdade.
const CHAVE_DE_EXEMPLO = 'exemplo-do-material';

// O bloco que responde "instalacao", "como rodar" e "chave de exemplo".
// Ele mora no documento porque e a pergunta que surge DEPOIS que a pessoa ja
// entendeu o que a rota faz: e como eu subo isso aqui?
const COMO_RODAR = {
  exige: {
    node: '18 ou superior',
    banco: 'qualquer servidor MySQL ou MariaDB',
  },
  passos: [
    'npm install',
    'copiar env.exemplo para .env e preencher com a credencial local',
    'npm start',
    'npm test',
  ],
  chaveDeExemplo: 'Authorization: Bearer ' + CHAVE_DE_EXEMPLO,
  documentacao: 'a rota GET /documentacao devolve este arquivo em JSON',
};

// ================================================ 1. a definicao das rotas
//
// Cada rota declara o que ACEITA e o que pode falhar. O codigo HTTP do erro
// esta AQUI, junto do codigo de erro — nunca dentro do handler. E por isso que
// o handler nao consegue responder 404 numa rota que o documento diz que
// responde 200: o status vem da mesma tabela que gerou o documento.

// A resposta que o servidor da para qualquer caminho fora da tabela. Ela nao
// pertence a uma rota, entao no documento mora fora de `paths`. Esquecer dela
// e o jeito classico de o cliente receber 404 e nao saber o que aquilo quer
// dizer.
const RESPOSTA_PADRAO = {
  status: 404,
  codigo: 'ROTA_DESCONHECIDA',
  frase: 'o caminho nao existe nesta API',
  exemplo: { erro: 'ROTA_DESCONHECIDA', mensagem: 'o caminho nao existe nesta API' },
};

const ROTAS = [
  {
    metodo: 'GET',
    caminho: '/produtos',
    resumo: 'lista os produtos',
    operacao: 'listarProdutos',
    descricao: 'Devolve os produtos cadastrados, do id mais baixo para o mais '
      + 'alto. Aceita filtro por nome e um limite de itens.',
    exemploRequisicao: 'GET /produtos?nm_item=mouse&limite=10',
    seguranca: false,
    parametros: [
      {
        nome: 'nm_item', in: 'query', tipo: 'string', obrigatorio: false,
        minimo: 1, maximo: 40, exemplo: 'mouse',
        descricao: 'filtra pelo nome do produto, ignorando caixa e espaco das pontas',
      },
      {
        nome: 'limite', in: 'query', tipo: 'integer', obrigatorio: false,
        minimo: 1, maximo: 100, exemplo: '10',
        descricao: 'quantos itens a resposta traz no maximo',
      },
    ],
    corpo: null,
    respostas: [
      {
        status: 200,
        frase: 'lista de produtos',
        exemplo: { produtos: [{ id: 1, nm_item: 'mouse', qtd: 5 }] },
      },
    ],
    erros: [
      {
        codigo: 'PARAMETRO_INVALIDO', status: 400,
        frase: 'parametro fora do formato declarado',
        exemplo: { erro: 'PARAMETRO_INVALIDO', mensagem: 'limite precisa ser numero inteiro' },
      },
    ],
  },
  {
    metodo: 'GET',
    caminho: '/produtos/{id}',
    resumo: 'devolve um produto pelo id',
    operacao: 'obterProduto',
    descricao: 'Devolve um produto. O id e obrigatorio e precisa ser inteiro.',
    exemploRequisicao: 'GET /produtos/1',
    seguranca: false,
    parametros: [
      {
        nome: 'id', in: 'path', tipo: 'integer', obrigatorio: true,
        minimo: 1, exemplo: '1',
        descricao: 'identificador do produto, o que a tabela tb_d14a1_produto gravou',
      },
    ],
    corpo: null,
    respostas: [
      {
        status: 200,
        frase: 'o produto pedido',
        exemplo: { id: 1, nm_item: 'mouse', qtd: 5 },
      },
    ],
    erros: [
      {
        codigo: 'PARAMETRO_INVALIDO', status: 400,
        frase: 'parametro fora do formato declarado',
        exemplo: { erro: 'PARAMETRO_INVALIDO', mensagem: 'id precisa ser numero inteiro' },
      },
      {
        codigo: 'ITEM_NAO_ENCONTRADO', status: 404,
        frase: 'o id nao existe na tabela',
        exemplo: { erro: 'ITEM_NAO_ENCONTRADO', mensagem: 'nao existe produto com esse id' },
      },
    ],
  },
  {
    metodo: 'POST',
    caminho: '/produtos',
    resumo: 'cadastra um produto',
    operacao: 'cadastrarProduto',
    descricao: 'Cadastra um produto novo. Exige cabecalho Authorization e corpo '
      + 'com nm_item e qtd.',
    exemploRequisicao: 'POST /produtos com o corpo do exemplo e a chave de exemplo',
    seguranca: true,
    parametros: [],
    corpo: {
      descricao: 'o produto que quer cadastrar',
      campos: [
        {
          nome: 'nm_item', tipo: 'string', obrigatorio: true,
          minimo: 3, maximo: 40, exemplo: 'monitor',
          descricao: 'nome do produto; unico na tabela',
        },
        {
          nome: 'qtd', tipo: 'integer', obrigatorio: true,
          minimo: 1, maximo: 9999, exemplo: 5,
          descricao: 'quantidade em estoque',
        },
      ],
    },
    respostas: [
      {
        status: 201,
        frase: 'o produto cadastrado, com o id que o banco gerou',
        exemplo: { id: 3, nm_item: 'monitor', qtd: 5 },
      },
    ],
    erros: [
      {
        codigo: 'CAMPO_OBRIGATORIO', status: 400,
        frase: 'campo obrigatorio ausente no corpo',
        exemplo: { erro: 'CAMPO_OBRIGATORIO', mensagem: 'nm_item e obrigatorio' },
      },
      {
        codigo: 'PARAMETRO_INVALIDO', status: 400,
        frase: 'campo com tipo ou tamanho fora do declarado',
        exemplo: { erro: 'PARAMETRO_INVALIDO', mensagem: 'qtd precisa ser numero inteiro' },
      },
      {
        codigo: 'SEM_CHAVE', status: 401,
        frase: 'a rota exige o cabecalho Authorization',
        exemplo: { erro: 'SEM_CHAVE', mensagem: 'falta o cabecalho Authorization' },
      },
      {
        codigo: 'ITEM_DUPLICADO', status: 409,
        frase: 'o nome ja existe na tabela',
        exemplo: { erro: 'ITEM_DUPLICADO', mensagem: 'esse nome ja existe' },
      },
    ],
  },
];

// ================================================= 2. o documento OpenAPI
//
// `exemploCorpo(corpo)` monta o exemplo de requisicao a partir da declaracao
// dos campos: o exemplo nao e digitado a mao, ele sai dos mesmos valores que
// o validador exige.
function exemploCorpo(corpo) {
  const exemplo = {};
  for (const campo of corpo.campos) exemplo[campo.nome] = campo.exemplo;
  return exemplo;
}

// `gerarOpenAPI(rotas, opcoes)` e o unico lugar que escreve o documento.
//
// `opcoes.detalhado === false` gera o documento "de venda": os mesmos
// caminhos, os mesmos metodos, os mesmos nomes de rota — e nada do que diz o
// que a API aceita. E o mesmo codigo com a flag oposta, e por isso que a
// comparacao do fim do exemplo e justa.
function gerarOpenAPI(rotas, opcoes = {}) {
  const detalhado = opcoes.detalhado !== false;
  const caminhos = {};

  for (const rota of rotas) {
    const metodo = rota.metodo.toLowerCase();
    if (!caminhos[rota.caminho]) caminhos[rota.caminho] = {};
    const operacao = { summary: rota.resumo, operationId: rota.operacao };

    if (detalhado) operacao.description = rota.descricao;

    if (rota.parametros.length > 0) {
      operacao.parameters = rota.parametros.map((p) => {
        // Sem `detalhado`, sobra so o par nome/tipo-de-uso. E o suficiente para
        // a pagina parecer completa e insuficiente para chamar a rota.
        const declarado = { name: p.nome, in: p.in };
        if (detalhado) {
          declarado.required = Boolean(p.obrigatorio) || p.in === 'path';
          declarado.description = p.descricao;
          declarado.schema = { type: p.tipo };
          declarado.example = p.exemplo;
        }
        return declarado;
      });
    }

    if (rota.corpo) {
      const propriedades = {};
      const obrigatorios = [];
      for (const campo of rota.corpo.campos) {
        obrigatorios.push(campo.nome);
        propriedades[campo.nome] = detalhado
          ? { type: campo.tipo, description: campo.descricao, example: campo.exemplo }
          : {};
      }
      const corpoDoDocumento = {};
      if (detalhado) {
        corpoDoDocumento.schema = {
          type: 'object',
          required: obrigatorios,
          properties: propriedades,
        };
        corpoDoDocumento.example = exemploCorpo(rota.corpo);
      }
      operacao.requestBody = {
        required: true,
        content: { 'application/json': corpoDoDocumento },
      };
    }

    // As respostas de sucesso e os erros entram na MESMA tabela do documento.
    // Um status so pode aparecer uma vez, entao os dois `400` da rota de POST
    // viram uma resposta com os dois codigos em `x-codigos`.
    operacao.responses = {};
    const respostas = rota.respostas.concat(rota.erros);
    for (const r of respostas) {
      const chave = String(r.status);
      const anterior = operacao.responses[chave];
      if (anterior && detalhado) {
        // A descricao fica com a frase do primeiro; os codigos se acumulam em
        // `x-codigos`, que e o que o cliente compara para decidir o que fazer.
        anterior['x-codigos'].push(r.codigo);
        continue;
      }
      const nova = { description: r.frase };
      if (detalhado) {
        nova['x-codigos'] = r.codigo ? [r.codigo] : [];
        nova.content = { 'application/json': { example: r.exemplo } };
      }
      operacao.responses[chave] = nova;
    }

    if (rota.seguranca) {
      operacao.security = [{ bearerAuth: [] }];
    }

    caminhos[rota.caminho][metodo] = operacao;
  }

  return {
    openapi: opcoes.versao,
    info: {
      title: opcoes.titulo,
      version: opcoes.versaoApi,
      description: opcoes.descricao,
    },
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          description: 'a chave vai no cabecalho Authorization, prefixo Bearer',
        },
      },
    },
    'x-resposta-padrao': {
      status: RESPOSTA_PADRAO.status,
      codigo: RESPOSTA_PADRAO.codigo,
      exemplo: RESPOSTA_PADRAO.exemplo,
    },
    'x-como-rodar': opcoes.comoRodar,
    paths: caminhos,
  };
}

// ================================================== 3. a auditoria do doc

// `esqueleto(objeto, recuo, nivel)` devolve as CHAVES do objeto, com o
// caminho completo de cada uma. E a forma que cabe numa pagina: o Swagger UI
// le as chaves, nao os valores, e a lista de chaves mostra quais informacoes
// a operacao carrega — inclusive as que faltam. Desce tres niveis e para: mais
// fundo que isso e o valor do exemplo, que a tabela do bloco 1 ja mostrou.
function esqueleto(objeto, recuo = 0, nivel = 0) {
  if (nivel > 2 || objeto === null || typeof objeto !== 'object') return '';
  const linhas = [];
  for (const [chave, valor] of Object.entries(objeto)) {
    const espaco = ' '.repeat(recuo + nivel * 2);
    if (Array.isArray(valor)) {
      linhas.push(espaco + chave + '[]' + (valor.length ? ' (' + valor.length + ')' : ''));
    } else if (valor && typeof valor === 'object') {
      linhas.push(espaco + chave + ' {');
      linhas.push(esqueleto(valor, recuo, nivel + 1));
      linhas.push(espaco + '}');
    } else {
      linhas.push(espaco + chave);
    }
  }
  return linhas.filter(Boolean).join('\n');
}

// `auditarDocumento(doc, rotas)` devolve uma lista de itens com nome, se
// passou e por quê. Nada e conferido por opiniao: cada item e uma conta feita
// sobre o documento e sobre a definicao das rotas.
function auditarDocumento(doc, rotas) {
  const contagem = {
    rota: { ok: 0, total: 0 },
    parametro: { ok: 0, total: 0 },
    requisicao: { ok: 0, total: 0 },
    resposta: { ok: 0, total: 0 },
    erro: { ok: 0, total: 0 },
    padrao: { ok: 0, total: 1 },
    ambiente: { ok: 0, total: 1 },
  };
  const falhas = [];

  for (const rota of rotas) {
    const op = (doc.paths[rota.caminho] || {})[rota.metodo.toLowerCase()];
    contagem.rota.total += 1;
    if (op) contagem.rota.ok += 1;
    else falhas.push('sem operacao para ' + rota.metodo + ' ' + rota.caminho);

    // `documentar parametro`: no caminho e no corpo, o tipo tem de estar
    // escrito e a obrigatoriedade tambem. Sem os dois, o cliente so descobre o
    // formato quando leva 400.
    for (const p of rota.parametros) {
      contagem.parametro.total += 1;
      const declarado = (op && op.parameters || []).find((d) => d.name === p.nome);
      const completo = declarado && declarado.schema && declarado.schema.type
        && typeof declarado.required === 'boolean';
      if (completo) contagem.parametro.ok += 1;
      else falhas.push(p.nome + ' (' + p.in + ') sem tipo e sem obrigatoriedade');
    }

    if (rota.corpo) {
      contagem.requisicao.total += 1;
      const exemploDeclarado = op && op.requestBody
        && op.requestBody.content['application/json'].example;
      const esperado = exemploCorpo(rota.corpo);
      const bate = exemploDeclarado
        && Object.keys(esperado).every((k) => exemploDeclarado[k] === esperado[k]);
      if (bate) contagem.requisicao.ok += 1;
      else falhas.push(rota.metodo + ' ' + rota.caminho + ' sem exemplo de requisicao');
    }

    // `exemplo de resposta` e `codigo de erro`: cada status tem de trazer o
    // exemplo E o codigo que o cliente compara para decidir o que fazer.
    for (const r of rota.respostas.concat(rota.erros)) {
      contagem.resposta.total += 1;
      const declarada = op && op.responses[String(r.status)];
      if (declarada && declarada.content && declarada.content['application/json'].example) {
        contagem.resposta.ok += 1;
      } else falhas.push(r.status + ' de ' + rota.caminho + ' sem exemplo de resposta');

      if (r.codigo) {
        contagem.erro.total += 1;
        const codigos = (declarada && declarada['x-codigos']) || [];
        if (codigos.includes(r.codigo)) contagem.erro.ok += 1;
        else falhas.push(r.codigo + ' nao aparece em responses.' + r.status);
      }
    }
  }

  if (doc['x-resposta-padrao'] && doc['x-resposta-padrao'].codigo) contagem.padrao.ok += 1;
  else falhas.push('sem x-resposta-padrao para o caminho desconhecido');

  if (doc['x-como-rodar'] && doc['x-como-rodar'].passos.length > 0
    && doc.components.securitySchemes.bearerAuth) {
    contagem.ambiente.ok += 1;
  } else falhas.push('sem instalacao, sem como rodar ou sem o formato da chave');

  return { contagem, falhas };
}

// ======================================================= 4. a validacao
//
// `validarValor(declaracao, bruto, rotulo)` le a MESMA declaracao que foi para
// o documento. O tipo, o tamanho e a obrigatoriedade nao estao escritos duas
// vezes: o que esta no documento e o que barra a requisicao.
//
// Devolve `{ ok: true, valor }` ou `{ ok: false, motivo, frase }`, e `motivo`
// e o codigo de erro que o handler procura na tabela de erros da rota.
function validarValor(declaracao, bruto, rotulo) {
  const faltando = bruto === undefined || bruto === null || bruto === '';
  if (faltando) {
    if (!declaracao.obrigatorio) return { ok: true, valor: undefined };
    return { ok: false, motivo: 'CAMPO_OBRIGATORIO', frase: rotulo + ' e obrigatorio' };
  }

  if (declaracao.tipo === 'integer') {
    const n = Number(bruto);
    // `Number('10abc')` vale NaN e `Number('')` vale 0: sem o
    // `Number.isInteger` as duas passariam como numero.
    if (!Number.isInteger(n)) {
      return { ok: false, motivo: 'PARAMETRO_INVALIDO', frase: rotulo + ' precisa ser numero inteiro' };
    }
    if (declaracao.minimo !== undefined && n < declaracao.minimo) {
      return { ok: false, motivo: 'PARAMETRO_INVALIDO', frase: rotulo + ' precisa ser maior ou igual a ' + declaracao.minimo };
    }
    if (declaracao.maximo !== undefined && n > declaracao.maximo) {
      return { ok: false, motivo: 'PARAMETRO_INVALIDO', frase: rotulo + ' precisa ser menor ou igual a ' + declaracao.maximo };
    }
    return { ok: true, valor: n };
  }

  const s = String(bruto);
  if (declaracao.minimo !== undefined && s.length < declaracao.minimo) {
    return { ok: false, motivo: 'PARAMETRO_INVALIDO', frase: rotulo + ' precisa ter ao menos ' + declaracao.minimo + ' caracteres' };
  }
  if (declaracao.maximo !== undefined && s.length > declaracao.maximo) {
    return { ok: false, motivo: 'PARAMETRO_INVALIDO', frase: rotulo + ' precisa ter no maximo ' + declaracao.maximo + ' caracteres' };
  }
  return { ok: true, valor: s };
}

// `statusDoErro(rota, codigo)` e o unico lugar que traduz codigo de erro em
// status HTTP. Se o codigo nao esta declarado, devolve 500 — e a falha aparece
// na auditoria, nao em producao.
function statusDoErro(rota, codigo) {
  const achado = rota.erros.find((e) => e.codigo === codigo);
  return achado ? achado.status : 500;
}

// ==================================================== 5. o roteador e os handlers
// O caminho com `{id}` vira expressao regular uma vez, na montagem. Sem isso o
// roteador teria de cortar a string na mao em toda requisicao.
function criarRoteador(rotas) {
  const tabela = rotas.map((rota) => {
    const nomes = [];
    const padrao = rota.caminho.replace(/\{(\w+)\}/g, (_, nome) => {
      nomes.push(nome);
      return '([^/]+)';
    });
    return { rota, expressao: new RegExp('^' + padrao + '$'), nomes };
  });

  return function casa(metodo, caminho) {
    for (const item of tabela) {
      if (item.rota.metodo !== metodo) continue;
      const achado = item.expressao.exec(caminho);
      if (!achado) continue;
      const params = {};
      item.nomes.forEach((nome, i) => {
        params[nome] = decodeURIComponent(achado[i + 1]);
      });
      return { rota: item.rota, params };
    }
    return null;
  };
}

const HANDLERS = {
  async listarProdutos(ctx) {
    const filtros = [];
    const valores = [];
    if (ctx.params.nm_item !== undefined) {
      filtros.push('nm_item LIKE ?');
      valores.push('%' + ctx.params.nm_item + '%');
    }
    const limite = ctx.params.limite === undefined ? 100 : ctx.params.limite;
    const sql = 'SELECT id, nm_item, qtd FROM tb_d14a1_produto'
      + (filtros.length ? ' WHERE ' + filtros.join(' AND ') : '')
      + ' ORDER BY id LIMIT ?';
    // O limite vai como valor do `?`, nunca colado no SQL: o documento diz que
    // ele e inteiro de 1 a 100, e e o validador que garante isso.
    const [linhas] = await ctx.banco.execute(sql, [...valores, limite]);
    return { status: 200, corpo: { produtos: linhas } };
  },

  async obterProduto(ctx) {
    const [linhas] = await ctx.banco.execute(
      'SELECT id, nm_item, qtd FROM tb_d14a1_produto WHERE id = ?',
      [ctx.params.id]
    );
    if (linhas.length === 0) {
      return { status: statusDoErro(ROTAS[1], 'ITEM_NAO_ENCONTRADO'),
        corpo: { erro: 'ITEM_NAO_ENCONTRADO', mensagem: 'nao existe produto com esse id' } };
    }
    return { status: 200, corpo: linhas[0] };
  },

  async cadastrarProduto(ctx) {
    const [gravado] = await ctx.banco.execute(
      'INSERT INTO tb_d14a1_produto (nm_item, qtd) VALUES (?, ?)',
      [ctx.corpo.nm_item, ctx.corpo.qtd]
    );
    return { status: 201, corpo: { id: gravarId(gravado), nm_item: ctx.corpo.nm_item, qtd: ctx.corpo.qtd } };
  },
};

// `gravarId(resultado)` le o id que o banco gerou. O `mysql2` devolve o
// `insertId` como numero grande, e ele so existe no resultado do INSERT.
function gravarId(resultado) {
  return Number(resultado.insertId);
}

// ================================================== 6. o servidor completo
function criarServidor(banco, casa) {
  return http.createServer(async (req, res) => {
    const responde = (status, corpo) => {
      res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
      res.end(JSON.stringify(corpo));
    };

    const url = new URL(req.url, 'http://127.0.0.1');

    // A propria documentacao e uma rota. Ela responde com o mesmo objeto que o
    // arquivo `openapi.json` do projeto vai ter.
    if (req.method === 'GET' && url.pathname === '/documentacao') {
      return responde(200, globalThis.DOCUMENTO_DA_AULA);
    }

    const achado = casa(req.method, url.pathname);
    if (!achado) {
      return responde(RESPOSTA_PADRAO.status, RESPOSTA_PADRAO.exemplo);
    }
    const rota = achado.rota;

    // A chave entra antes de qualquer consulta: sem ela nao ha o que ler.
    if (rota.seguranca && !req.headers.authorization) {
      return responde(statusDoErro(rota, 'SEM_CHAVE'),
        { erro: 'SEM_CHAVE', mensagem: 'falta o cabecalho Authorization' });
    }

    // Validacao lida da declaracao, campo por campo. Cada falha devolve o
    // codigo declarado na rota — e o codigo que o documento tambem publica.
    const params = {};
    for (const p of rota.parametros) {
      const bruto = p.in === 'path'
        ? achado.params[p.nome]
        : url.searchParams.get(p.nome);
      const veredito = validarValor(p, bruto, p.nome);
      if (!veredito.ok) {
        return responde(statusDoErro(rota, veredito.motivo),
          { erro: veredito.motivo, mensagem: veredito.frase });
      }
      params[p.nome] = veredito.valor;
    }

    let corpo = {};
    if (rota.corpo) {
      const bruto = await lerCorpo(req);
      if (bruto === null) {
        return responde(statusDoErro(rota, 'PARAMETRO_INVALIDO'),
          { erro: 'PARAMETRO_INVALIDO', mensagem: 'corpo nao e JSON valido' });
      }
      for (const campo of rota.corpo.campos) {
        const veredito = validarValor(campo, bruto[campo.nome], campo.nome);
        if (!veredito.ok) {
          return responde(statusDoErro(rota, veredito.motivo),
            { erro: veredito.motivo, mensagem: veredito.frase });
        }
        corpo[campo.nome] = veredito.valor;
      }
    }

    try {
      const saida = await HANDLERS[rota.operacao]({ banco, params, corpo });
      return responde(saida.status, saida.corpo);
    } catch (erro) {
      // `ER_DUP_ENTRY` e o unico erro do banco que a API trata com nome
      // proprio: o documento promete 409 ITEM_DUPLICADO e e isso que o
      // cliente precisa receber para oferecer outra opcao.
      if (erro.code === 'ER_DUP_ENTRY' && rota.erros.some((e) => e.codigo === 'ITEM_DUPLICADO')) {
        console.error('duplicado no banco: ' + erro.code + ' - ' + erro.message);
        return responde(statusDoErro(rota, 'ITEM_DUPLICADO'),
          { erro: 'ITEM_DUPLICADO', mensagem: 'esse nome ja existe' });
      }
      console.error('falha interna: ' + (erro.code || erro.name) + ' - ' + erro.message);
      return responde(500, { erro: 'ERRO_INTERNO', mensagem: 'falha interna, o time foi avisado' });
    }
  });
}

// `lerCorpo(req)` junta os pedaços da requisicao e devolve o objeto. Devolve
// `null` quando o corpo nao e JSON valido, e o chamador transforma isso no
// 400 declarado.
async function lerCorpo(req) {
  const partes = [];
  for await (const pedaco of req) partes.push(pedaco);
  if (!partes.length) return {};
  try {
    return JSON.parse(Buffer.concat(partes).toString('utf8'));
  } catch (_) {
    return null;
  }
}

// ============================================== 7. a auditoria na linha
// `cobre(doc, rota, status)` pergunta ao documento se ele publica um status
// que o servidor acabou de devolver. A pergunta e feita no sentido inverso ao
// da auditoria: nao e "o servidor devolveu o que prometia", e "tudo que o
// servidor devolveu esta no documento".
function cobre(doc, rota, status) {
  const op = (doc.paths[rota.caminho] || {})[rota.metodo.toLowerCase()];
  return Boolean(op && op.responses[String(status)]);
}

async function main() {
  const banco = await createConnection({
    host: process.env.DB_HOST,
    port: Number(process.env.DB_PORT),
    user: process.env.DB_USER,
    password: process.env.DB_PASS,
    database: process.env.DB_NAME,
    multipleStatements: true,
  });

  // A versao e capturada, nunca afirmada: a maquina de quem roda devolve o que
  // ela tem, e o README nao pode escrever um numero que so vale aqui.
  const [versao] = await banco.query('SELECT VERSION() AS versao');
  console.log('banco em uso: ' + versao[0].versao);

  await banco.query(`
    CREATE TABLE IF NOT EXISTS tb_d14a1_produto (
      id      INT AUTO_INCREMENT PRIMARY KEY,
      nm_item VARCHAR(40) NOT NULL UNIQUE,
      qtd     INT NOT NULL DEFAULT 1
    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
  `);
  // `TRUNCATE` no comeco: rodar duas vezes tem que dar o mesmo resultado, e o
  // id do produto novo tem de ser sempre o mesmo.
  await banco.query('TRUNCATE TABLE tb_d14a1_produto');
  await banco.query(
    'INSERT INTO tb_d14a1_produto (nm_item, qtd) VALUES (?, ?), (?, ?)',
    ['mouse', 5, 'teclado', 2]
  );

  // ---------------------------------------------------- o documento
  const OPCOES = {
    titulo: 'API de produtos do material',
    descricao: 'Cadastro de produtos em MySQL, escrito com Node.js e documentado em OpenAPI.',
    versao: VERSAO_OPENAPI,
    versaoApi: VERSAO_DA_API,
    comoRodar: COMO_RODAR,
  };

  const doc = gerarOpenAPI(ROTAS, OPCOES);
  const docDeVenda = gerarOpenAPI(ROTAS, Object.assign({}, OPCOES, { detalhado: false }));
  globalThis.DOCUMENTO_DA_AULA = doc;

  // ------------------------------------------- a tabela que a pessoa procura
  // A tabela e montada com quebra automatica: o status do erro tem 4 entradas
  // numa das rotas, e uma linha de 300 caracteres nao cabe em lugar nenhum.
  // `quebra()` devolve o texto partido em linhas de no maximo `largura`.
  function quebra(texto, largura, recuo) {
    const palavras = String(texto).split(' ');
    const linhas = [];
    let atual = '';
    for (const p of palavras) {
      if (atual && (atual.length + 1 + p.length) > largura) {
        linhas.push(atual);
        atual = p;
      } else {
        atual = atual ? atual + ' ' + p : p;
      }
    }
    if (atual) linhas.push(atual);
    return linhas.map((l, i) => (i === 0 ? l : ' '.repeat(recuo) + l));
  }

  console.log('\n--- 1. a tabela das rotas, a mesma que virou o documento ---');
  // As colunas com largura fixa; a quinta cresce porque o status de erro tem
  // quatro entradas na rota de POST e nao cabe em 26 caracteres.
  const COLUNAS = [
    { titulo: 'metodo', largura: 6, recuo: 0 },
    { titulo: 'caminho', largura: 18, recuo: 0 },
    { titulo: 'o que faz', largura: 23, recuo: 0 },
    { titulo: 'o que devolve', largura: 24, recuo: 0 },
    { titulo: 'status de erro', largura: 34, recuo: 0 },
  ];
  console.log(COLUNAS.map((c) => c.titulo.padEnd(c.largura)).join('  ').trimEnd());
  console.log(COLUNAS.map((c) => '-'.repeat(c.largura)).join('  '));

  for (const rota of ROTAS) {
    const celulas = [
      rota.metodo,
      rota.caminho,
      rota.resumo,
      rota.respostas.map((r) => r.status + ' ' + r.frase).join('; '),
      rota.erros.map((e) => e.status + ' ' + e.codigo).join('; '),
    ];
    const quebradas = COLUNAS.map((coluna, i) =>
      quebra(celulas[i], coluna.largura, 0));
    const altura = Math.max.apply(null, quebradas.map((c) => c.length));
    for (let linha = 0; linha < altura; linha++) {
      console.log(quebradas
        .map((c, i) => (c[linha] || '').padEnd(COLUNAS[i].largura))
        .join('  ').trimEnd());
    }
  }
  console.log('\no que devolve vem de `respostas`; o status do erro vem de `erros`,');
  console.log('nunca de uma frase escrita dentro do handler.');
  console.log('essa e a tabela que a pessoa procura antes de abrir o JSON — e ela');
  console.log('esta no `README.md`, gerada da mesma definicao que gerou o documento.');

  // ------------------------------------------ a estrutura do documento
  console.log('\n--- 2. a estrutura do documento OpenAPI ---');
  console.log('openapi      : ' + doc.openapi);
  console.log('info.title   : ' + doc.info.title);
  console.log('info.version : ' + doc.info.version);
  console.log('paths        : ' + Object.keys(doc.paths).length + ' caminhos, '
    + Object.values(doc.paths).reduce((n, p) => n + Object.keys(p).length, 0) + ' operacoes');
  console.log('x-como-rodar : ' + doc['x-como-rodar'].passos.length + ' passos, '
    + 'chave de exemplo declarada');
  console.log('x-resposta-padrao: ' + doc['x-resposta-padrao'].codigo
    + ' (status ' + doc['x-resposta-padrao'].status + ')');

  // A FORMA do documento, e nao o JSON inteiro: tres operacoes dumpadas viram
  // tres paredes de texto na pagina. O que o aluno precisa ver e quais chaves
  // existem dentro de cada operacao, e `esqueleto(objeto, recuo)` imprime so
  // as chaves — descendo tres niveis, o suficiente para `parameters`,
  // `requestBody` e `responses`, e parando antes do valor do exemplo.
  console.log('\nas chaves da operacao POST /produtos, na ordem em que o Swagger UI le:');
  console.log(esqueleto(doc.paths['/produtos'].post, 2));

  // O `parameters` do GET por id e o trecho que resume a aula inteira: o nome,
  // onde o parametro entra, o tipo, se e obrigatorio e o exemplo. Sao as cinco
  // informacoes que o documento "de venda" nao tinha.
  console.log('\n"parameters" da rota GET /produtos/{id}, declarados campo a campo:');
  console.log(JSON.stringify(
    doc.paths['/produtos/{id}'].get.parameters, null, 2));

  // A outra metade da pergunta: como eu subo isso aqui? O bloco `x-como-rodar`
  // e o `instalacao` + `como rodar` + `chave de exemplo` do README, no mesmo
  // objeto. A versao do banco NUNCA e escrita a mao — ela e capturada.
  console.log('\n--- 2b. a outra metade: instalar, rodar e a chave de exemplo ---');
  const readme = doc['x-como-rodar'];
  console.log('exige node: ' + readme.exige.node);
  console.log('exige banco: ' + readme.exige.banco);
  console.log('passos:');
  for (const passo of readme.passos) console.log('  ' + passo);
  console.log('chave de exemplo no documento: ' + readme.chaveDeExemplo);
  console.log('formato declarado em components.securitySchemes: '
    + doc.components.securitySchemes.bearerAuth.type + ' / '
    + doc.components.securitySchemes.bearerAuth.scheme);
  console.log('a chave de exemplo e um valor ficticio: nenhum segredo e');
  console.log('versionado, so o formato e o nome do cabecalho.');

  // ------------------------------------- a auditoria: completo x de venda
  console.log('\n--- 3. a mesma definicao, dois documentos ---');
  const completo = auditarDocumento(doc, ROTAS);
  const venda = auditarDocumento(docDeVenda, ROTAS);
  const rotulos = [
    ['rota', 'documentar rota'],
    ['parametro', 'documentar parametro'],
    ['requisicao', 'exemplo de requisicao'],
    ['resposta', 'exemplo de resposta'],
    ['erro', 'codigo de erro'],
    ['padrao', 'resposta padrao (caminho desconhecido)'],
    ['ambiente', 'instalacao, como rodar e chave'],
  ];
  console.log('item                                    completo   de venda');
  for (const [chave, nome] of rotulos) {
    const a = completo.contagem[chave];
    const b = venda.contagem[chave];
    console.log(nome.padEnd(40) + (a.ok + '/' + a.total).padEnd(11)
      + (b.ok + '/' + b.total));
  }
  console.log('o documento de venda tem os mesmos ' + Object.keys(docDeVenda.paths).length
    + ' caminhos e os mesmos nomes de rota.');
  console.log('o que falta e o que diz o que a API ACEITA — e sao ' + venda.falhas.length
    + ' lacunas, agrupadas por tipo:');
  // Agrupar e o que torna a lista legivel: as 21 lacunas sao 3 defeitos
  // repetidos em varias rotas, e repetir "400 de /produtos sem exemplo de
  // resposta" quatro vezes nao ensina nada que a primeira vez nao ensinou.
  const porTipo = new Map();
  for (const f of venda.falhas) {
    const tipo = f.includes('sem exemplo de requisicao') ? 'exemplo de requisicao ausente'
      : f.includes('sem exemplo de resposta') ? 'exemplo de resposta ausente'
        : f.includes('sem tipo e sem obrigatoriedade') ? 'parametro sem tipo e sem obrigatoriedade'
          : 'codigo de erro ausente em responses';
    porTipo.set(tipo, (porTipo.get(tipo) || 0) + 1);
  }
  for (const [tipo, n] of porTipo) {
    console.log('  ' + String(n).padStart(2) + 'x  ' + tipo);
  }
  console.log('as tres primeiras linhas do exemplo sao exatamente o que o');
  console.log('documento de venda nao diz: o nome do parametro existe, e o');
  console.log('formato, a obrigatoriedade e o limite, nao.');

  // =================================================== 7. o servidor no ar
  const casa = criarRoteador(ROTAS);
  const servidor = criarServidor(banco, casa);

  await new Promise((r) => servidor.listen(0, '127.0.0.1', r));
  const base = 'http://127.0.0.1:' + servidor.address().port;
  console.log('\n--- 4. o que o servidor devolve, e se o documento cobre ---');
  console.log('servidor no ar em ' + base);
  console.log('a porta muda a cada execucao: e o listen(0) pedindo uma livre ao sistema');

  const cabecalho = { Authorization: 'Bearer ' + CHAVE_DE_EXEMPLO };

  // Os casos vem da propria definicao: o corpo do POST e o exemplo que o
  // documento publica, nao um corpo digitado aqui.
  const corpoDoDocumento = exemploCorpo(ROTAS[2].corpo);

  const casos = [
    {
      nome: 'GET da lista, com o filtro e o limite do exemplo',
      rota: ROTAS[0], metodo: 'GET', caminho: '/produtos?nm_item=mouse&limite=10',
      detalhes: '200 traz o filtro declarado: so o nome que casa',
    },
    {
      nome: 'GET de um id que existe',
      rota: ROTAS[1], metodo: 'GET', caminho: '/produtos/1',
    },
    {
      nome: 'GET de um id que nao existe',
      rota: ROTAS[1], metodo: 'GET', caminho: '/produtos/9999',
      detalhes: '404 ITEM_NAO_ENCONTRADO, declarado na rota e no documento',
    },
    {
      nome: 'GET com id que nao e inteiro',
      rota: ROTAS[1], metodo: 'GET', caminho: '/produtos/abc',
      detalhes: '400 PARAMETRO_INVALIDO: o documento ja dizia que id e inteiro',
    },
    {
      nome: 'GET com limite acima do maximo declarado',
      rota: ROTAS[0], metodo: 'GET', caminho: '/produtos?limite=500',
      detalhes: '400 PARAMETRO_INVALIDO: maximo 100 escrito no mesmo lugar da regra',
    },
    {
      nome: 'POST com a chave de exemplo e o exemplo de requisicao do documento',
      rota: ROTAS[2], metodo: 'POST', caminho: '/produtos',
      cabecalhos: cabecalho, corpo: corpoDoDocumento,
      detalhes: '201 com o id que o banco gerou',
    },
    {
      nome: 'POST sem a chave',
      rota: ROTAS[2], metodo: 'POST', caminho: '/produtos',
      corpo: corpoDoDocumento,
      detalhes: '401 SEM_CHAVE antes de tocar no banco',
    },
    {
      nome: 'POST sem o campo obrigatorio',
      rota: ROTAS[2], metodo: 'POST', caminho: '/produtos',
      cabecalhos: cabecalho, corpo: { qtd: 1 },
      detalhes: '400 CAMPO_OBRIGATORIO',
    },
    {
      nome: 'POST com nome repetido',
      rota: ROTAS[2], metodo: 'POST', caminho: '/produtos',
      cabecalhos: cabecalho, corpo: { nm_item: 'mouse', qtd: 1 },
      detalhes: '409 ITEM_DUPLICADO: ER_DUP_ENTRY traduzido para o codigo declarado',
    },
    {
      nome: 'GET num caminho que nao esta na tabela',
      rota: null, metodo: 'GET', caminho: '/nao-existe',
      detalhes: 'a resposta padrao, que o documento publica fora de paths',
    },
  ];

  let cobriuTodos = 0;
  for (const caso of casos) {
    // A linha de contexto vem ANTES da requisicao. O `console.error` do
    // servidor sai no stderr, que a pagina nao embute, e uma linha de erro
    // solta na saida real deixa o aluno sem saber o que ela estava provando.
    console.log('\n' + caso.nome);
    if (caso.corpo !== undefined) console.log('  corpo enviado: ' + JSON.stringify(caso.corpo));

    const opcoes = { method: caso.metodo };
    if (caso.cabecalhos) opcoes.headers = caso.cabecalhos;
    if (caso.corpo !== undefined) {
      opcoes.headers = Object.assign({}, caso.cabecalhos,
        { 'Content-Type': 'application/json' });
      opcoes.body = JSON.stringify(caso.corpo);
    }
    const resposta = await fetch(base + caso.caminho, opcoes);
    const texto = await resposta.text();
    const registrado = (caso.rota
      ? (doc.paths[caso.rota.caminho][caso.rota.metodo.toLowerCase()].responses[String(resposta.status)] || null)
      : doc['x-resposta-padrao']);
    const noDocumento = caso.rota ? cobre(doc, caso.rota, resposta.status)
      : resposta.status === doc['x-resposta-padrao'].status;
    if (noDocumento) cobriuTodos += 1;

    console.log('  resposta    : ' + resposta.status + ' ' + texto);
    // O que o documento publica para aquele status: o codigo, quando existe, e
    // o exemplo do corpo. Uma resposta de sucesso nao tem codigo de erro, e a
    // linha mostra o exemplo — que e o que o cliente copia para provar.
    // `x-resposta-padrao` tem um `codigo` solto e nao a lista `x-codigos`, e e
    // por isso que os dois formatos sao lidos aqui em vez de num so lugar.
    const codigos = registrado && (registrado['x-codigos'] || [registrado.codigo])
      .filter(Boolean);
    const exemplo = registrado && registrado.content
      && registrado.content['application/json'].example;
    console.log('  documento   : ' + (noDocumento
      ? 'publica o status ' + resposta.status
        + (codigos.length
          ? ' (' + codigos.join(', ') + ')'
          : ' com o exemplo ' + JSON.stringify(exemplo))
      : 'NAO publica o status ' + resposta.status + ' — divergencia'));
    if (caso.detalhes) console.log('  ' + caso.detalhes);
  }
  console.log('\n' + cobriuTodos + ' de ' + casos.length
    + ' respostas do servidor estao cobertas pelo documento.');

  // O exemplo de requisicao do documento e o corpo que foi enviado de verdade:
  console.log('corpo do exemplo no documento: ' + JSON.stringify(corpoDoDocumento));
  console.log('foi esse corpo que o POST recebeu, sem reescrita — o exemplo nao e');
  console.log('uma foto antiga: ele sai dos campos declarados em `corpo.campos`.');

  // =================================================== 8. o exemplo de resposta
  // O exemplo de resposta do documento precisa ter as mesmas chaves do que o
  // servidor devolveu. E a conferencia que pega o "quase igual".
  const [gravado] = await banco.execute(
    'SELECT id, nm_item, qtd FROM tb_d14a1_produto WHERE nm_item = ?', ['monitor']);
  const exemplo201 = doc.paths['/produtos'].post.responses['201'].content['application/json'].example;
  const clavesExemplo = Object.keys(exemplo201).sort().join(',');
  const chavesReais = Object.keys(gravado[0]).sort().join(',');
  console.log('\n--- 5. o exemplo de resposta casa com a resposta de verdade? ---');
  console.log('exemplo no documento: ' + JSON.stringify(exemplo201));
  console.log('linha no banco      : ' + JSON.stringify(gravado[0]));
  console.log('chaves: ' + (clavesExemplo === chavesReais ? 'iguais (' + chavesReais + ')' : 'DIFERENTES'));

  // O banco ficou como o documento diz: duas linhas do seed e o produto novo.
  const [total] = await banco.query('SELECT COUNT(*) AS total FROM tb_d14a1_produto');
  console.log('linhas na tabela depois de todos os casos: ' + total[0].total);

  await new Promise((r) => servidor.close(r));
  console.log('\nservidor encerrado com close().');

  await banco.end();
}

main().catch((erro) => {
  console.error('falhou:', erro.code || erro.name, '-', erro.message);
  process.exit(1);
});