Especificação OpenAPI

O arquivo

Baixar openscale-openapi-v1.yaml

Formato	OpenAPI 3.1.0
Operações	510, em 382 caminhos
Escritas à mão, com esquemas completos	159
Geradas do código	351, marcadas com x-auto: true
Idioma	Inglês

O arquivo publicado aqui tem os exemplos neutralizados: endereços, nomes de estação e identificadores do ambiente de desenvolvimento foram trocados por valores de documentação. Os valores de contrato — const, enum e os caminhos — são os reais.

Como ela é produzida

Gerada do roteamento real do produto, não de uma lista mantida à mão. Isso tem uma consequência que vale declarar: a especificação não pode descrever rota que não existe, porque ela não é escrita — é lida.

As operações marcadas x-auto: true trazem caminho, método, parâmetros, guarda de acesso e o arquivo de origem, todos exatos. O corpo e a resposta delas são genéricos. O marcador existe para tornar isso explícito em vez de fingir completude: 351 operações com corpo genérico e um marcador honesto são mais úteis que 351 esquemas inventados.

O gerador tem um modo de verificação que falha quando existe rota sem documentação — o que impede que uma rota nova entre sem aparecer aqui.

Uma limpeza que a geração provocou

Ao gerar do roteamento, dezessete operações documentadas apontavam para rotas que não existiam mais — funcionalidades descontinuadas cuja documentação sobreviveu. Foram removidas. Documentar rota que responde 404 é pior que não documentar, porque manda quem integra procurar o defeito no lugar errado.

Consumir em um cliente

O site não traz explorador de API embutido, de propósito: um explorador que executa requisição de dentro da página de documentação precisa de proxy, ou pede que o seu navegador chame o seu servidor a partir de outra origem — e a primeira coisa que ele encontra é a política de mesma origem. Cliente dedicado resolve isso melhor e você já vai usar um.

Hoppscotch

1. Baixe o arquivo acima.
2. Em Collections → Import/Export → Import → OpenAPI, selecione o arquivo.
3. Crie um ambiente com a variável baseUrl apontando para a sua instalação, com esquema: https://openscale.suaempresa.com.br.
4. Rode Authentication → gerar token bearer, o primeiro pedido da coleção. Ele grava a variável token, que as demais requisições usam.

Outros clientes

O arquivo é OpenAPI 3.1 padrão: Insomnia, Bruno, Postman e geradores de cliente o consomem sem conversão. Para gerar cliente:

npx @openapitools/openapi-generator-cli generate \
  -i openscale-openapi-v1.yaml -g typescript-fetch -o ./cliente-openscale

Problemas comuns ao testar pelo navegador

Três sintomas que aparecem sempre, e o que cada um é de verdade:

Toda requisição GET devolve HTML com status 200. Você está chamando o caminho da interface, não o da API. A aplicação serve a página para qualquer caminho não reconhecido, para que a navegação do lado do cliente funcione. Confira o prefixo: /manager-api/….

Erro de rede sem causa aparente. Cliente de API dentro do navegador está sujeito à política de mesma origem. Use o modo que não passa pelo navegador (agente nativo ou extensão do cliente), ou chame por curl.

Falha de proxy. O modo de proxy do cliente manda a requisição por um servidor intermediário, que não alcança uma instalação em rede interna. Para servidor interno, use o modo nativo do cliente.

Para integração de verdade, nenhum desses aparece: use o token bearer e chame direto do servidor.

Regenerar

A especificação é gerada no repositório do produto:

node scripts/api/gerar-openapi.mjs

E republicada neste site com os exemplos neutralizados:

node scripts/preparar-openapi.mjs