Validação e CI

Esta página descreve a qualidade automatizada e o fluxo de publicação do portal.

CI/CD em resumo

• Pull request: o GitHub Actions roda apenas a validação (npm ci + npm run ci = validate:openapi + validate:docs + build). Não publica nada.
• Push em main: roda a validação e, se verde, aciona o deploy de produção no Dokploy (via webhook seguro DOKPLOY_WEBHOOK_URL). O build que vai ao ar é feito pelo Dokploy (Dockerfile → Nginx servindo build/). Detalhes em Deploy (Dokploy).

O destino de publicação é o Dokploy/Nginx estático em https://finwaydocs.finaya.tech (GitHub Pages foi descartado).

Scripts disponíveis

Script	O que faz
npm run build	Build de produção; falha em links quebrados (onBrokenLinks: throw).
npm start	Servidor de desenvolvimento.
npm run serve	Serve o build localmente.
npm run validate:openapi	Valida static/finway.json com Spectral (.spectral.yaml, --fail-severity error).
npm run check:links	Verifica offline links de arquivo .md/.mdx (script próprio, sem rede).
npm run validate:docs	Validações leves de docs (front-matter, Scalar remanescente, fences, <details>).
npm run ci	Executa validate:openapi + validate:docs + build.

check:links não faz parte do ci por escolha: links de rota e externos já são cobertos pelo build (que agora é throw). O check:links é um apoio offline para links de arquivo.

API Reference: renderizada em runtime (decisão atual)

• A API Reference é renderizada em runtime pelo @scalar/docusaurus a partir de static/finway.json (servida em /finway.json). Não há páginas geradas nem etapa de pré-build — não existem mais os scripts gen:api/clean:api. [DECISÃO — DOCS-ADR-002, Atualização 2026-06-19]
• Quando finway.json mudar: substitua static/finway.json (a partir da origem) e rode npm run build. A referência reflete a nova spec automaticamente — nada a regenerar nem commitar além do próprio finway.json.
• O CI valida o contrato e o portal (npm run ci = validate:openapi + validate:docs + build). O build não depende de artefatos gerados de API.

Como validar o OpenAPI

npm run validate:openapi

O ruleset .spectral.yaml valida a estrutura do OpenAPI. Problemas legados conhecidos no finway.json foram rebaixados a warning (não quebram o CI) e devem ser corrigidos na origem:

Regra	Ocorrências	Natureza
path-params	16	Operações sob /holders/{document}/... não declaram o parâmetro {document}.
oas3-valid-media-example	14	Exemplos de parâmetro com tipo divergente do schema.
oas3-valid-schema-example	1	MetadataInfo.value.example com tipo divergente.
oas3-schema	1	Um parâmetro sem schema/content.

Quando esses itens forem corrigidos no finway.json (na origem), reverter as regras correspondentes para error no .spectral.yaml.

Como interpretar o build

• [SUCCESS] Generated static files in "build" → build OK.
• Com onBrokenLinks: throw e markdown.hooks.onBrokenMarkdownLinks: throw, qualquer link interno quebrado falha o build — corrija o link antes do merge.

Quando a API Reference divergir de finway.json

A referência é lida em runtime direto da spec, então não há cópia gerada para divergir. Se a referência em /api não refletir o esperado:

1. Confirme que static/finway.json está atualizado (fonte da verdade) e válido (npm run validate:openapi).
2. Rode npm run build e recarregue /api (limpe o cache do navegador, se necessário).
3. Nunca edite a referência no portal — toda correção vai ao finway.json na origem.