fix(docs): restaura prefixo /api nas URLs da documentação OpenAPI by felipeflfranca · Pull Request #908 · BrasilAPI/BrasilAPI · GitHub
Skip to content

fix(docs): restaura prefixo /api nas URLs da documentação OpenAPI - #908

Closed
felipeflfranca wants to merge 1 commit into
BrasilAPI:mainfrom
felipeflfranca:fix/docs-servers-prefixo-api
Closed

felipeflfranca wants to merge 1 commit into
BrasilAPI:mainfrom
felipeflfranca:fix/docs-servers-prefixo-api

Conversation

@felipeflfranca

@felipeflfranca felipeflfranca commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

Problema

Na documentação, ao expandir qualquer rota, a URL exibida vem sem o prefixo /api:

https://brasilapi.com.br/hospitais/v1     ← 404
https://brasilapi.com.br/api/hospitais/v1 ← correto

Quem copia a URL da documentação recebe 404. O problema afeta todas as rotas documentadas.

Causa

services/getJsonDoc.js funde todos os JSONs de pages/docs/doc/ com lodash.merge, em ordem alfabética de readdirSync. O basic_info.json é o dono da identidade global da spec e define corretamente:

"servers": [{ "url": "https://brasilapi.com.br/api" }]

Só que o eleicoes.json também declarava chaves globais:

"openapi": "3.0.0",
"info": { "title": "API de Eleições - BrasilAPI", ... },
"servers": [{ "url": "https://brasilapi.com.br" }]

Como eleicoes vem depois de basic_info no alfabeto, o merge sobrescreve servers[0].url e apaga o /api da spec inteira. Saída do merge antes da correção:

openapi : 3.0.0                          (esperado: 3.0.5)
title   : API de Eleições - BrasilAPI    (esperado: Brasil API)
servers : [{"url":"https://brasilapi.com.br"}]

O título e a descrição da home da documentação também estavam sendo sequestrados — não era só o /api.

Introduzido em dfa9354 (#874).

Solução

  • Remove openapi/info/servers do eleicoes.json. Seus paths já seguem a convenção do projeto (/eleicoes/..., relativos ao server), então nada muda para essas rotas além de voltarem a ganhar o prefixo correto.
  • Remove openapi de cid10.json e status.json, que causavam o mesmo clobbering na versão da spec.
  • getJsonDoc passa a ignorar essas chaves globais em qualquer arquivo que não seja o basic_info.json, para que um arquivo de endpoint não volte a derrubar a spec inteira em silêncio.
  • Testes de regressão cobrindo servers, identidade global, ausência de chaves globais nos arquivos de endpoint e o formato dos paths documentados.

Nenhum endpoint, campo de resposta ou status HTTP foi alterado — a mudança é restrita à montagem da documentação.

Verificação

  • npx vitest run tests/docs-spec-refs.test.js — 5/5 passando
  • npx eslint pages/ services/ lib/ util/ middlewares/ errors/ --ext .js — limpo
  • Documentação renderizada localmente: o campo da rota expandida passa a exibir https://brasilapi.com.br/api/cnpj/v1/{cnpj}, e o cabeçalho volta a "Brasil API (1.0.0)" com a descrição original
  • Smoke local: /api/hospitais/v1 → 200, /hospitais/v1 → 404

O getJsonDoc funde todos os JSONs de pages/docs/doc/ com lodash.merge em
ordem alfabética. O eleicoes.json declarava as chaves globais da spec
(openapi, info, servers) e, por vir depois de basic_info.json no alfabeto,
sobrescrevia servers[0].url com "https://brasilapi.com.br" — sem o /api.

O efeito não ficava restrito às rotas de eleições: toda a documentação
passou a exibir URLs sem o prefixo, que retornam 404 quando copiadas
(ex.: https://brasilapi.com.br/hospitais/v1). O info e a versão da spec
também eram sequestrados, trocando o título da página por "API de Eleições
- BrasilAPI".

- remove openapi/info/servers do eleicoes.json e openapi do cid10.json e
  status.json, que causavam o mesmo clobbering na versão da spec
- getJsonDoc passa a ignorar essas chaves globais em qualquer arquivo que
  não seja o basic_info.json, dono da identidade da spec
- testes de regressão cobrindo servers, identidade global e o formato dos
  paths documentados

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@vercel

vercel Bot commented Sep 10, 2026

Copy link
Copy Markdown

@sonarqubecloud

Copy link
Copy Markdown

@felipeflfranca

Copy link
Copy Markdown
Contributor Author

@felipeflfranca
felipeflfranca deleted the fix/docs-servers-prefixo-api branch September 10, 2026 18:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant