Swagger UI

O que é o Swagger UI, em termos simples?

Pense no Swagger UI como um manual de instruções interativo de uma API. Em vez de ler um documento estático, a pessoa abre uma página no navegador e vê todas as operações disponíveis organizadas em lista, com explicações sobre o que cada uma faz e quais dados ela espera receber.

Além de mostrar as informações, a página permite clicar em uma operação, preencher os campos e enviar uma requisição de verdade. A resposta da API aparece logo abaixo, com o código de status HTTP e o conteúdo retornado, geralmente em JSON.

Como o Swagger UI funciona?

O Swagger UI lê um arquivo de especificação no padrão OpenAPI, normalmente em JSON ou YAML. Esse arquivo descreve os endpoints da API, os métodos HTTP aceitos, os parâmetros, os esquemas dos dados e as formas de autenticação.

A partir dessa descrição, a ferramenta gera automaticamente a página de documentação. Quando a especificação muda, a página é atualizada junto, o que ajuda a manter a documentação sempre alinhada ao comportamento real da API.

Para que serve o Swagger UI em uma API fiscal?

Em uma API de emissão fiscal, o Swagger UI ajuda o desenvolvedor a descobrir rapidamente como emitir uma NF-e, NFS-e ou NFC-e, como consultar o status de um documento, cancelar uma nota ou baixar o XML e o PDF.

Ele é especialmente útil no início da integração: dá para montar um payload de teste, enviá-lo no ambiente de homologação e observar as respostas e rejeições antes de escrever o código definitivo no ERP ou na plataforma de vendas.

Qual a diferença entre Swagger UI e OpenAPI?

OpenAPI é a especificação, ou seja, o padrão que define como descrever uma API em um arquivo estruturado. Swagger UI é uma das ferramentas que leem esse arquivo e o exibem de forma visual e interativa.

Em resumo, o OpenAPI é o conteúdo e o Swagger UI é a vitrine. O mesmo arquivo OpenAPI pode ser usado por outras ferramentas, como geradores de código e validadores, sem depender do Swagger UI.

Como testar chamadas autenticadas no Swagger UI?

Muitas APIs exigem autenticação, como API Key ou Bearer token. O Swagger UI costuma exibir um botão de autorização onde o usuário informa sua credencial uma vez, e ela passa a ser enviada automaticamente no header das requisições de teste.

Por segurança, o ideal é usar credenciais do ambiente de homologação ao testar e nunca compartilhar telas ou capturas que exponham chaves de produção.

Exemplos de Swagger UI

• Um desenvolvedor de ERP abre o Swagger UI da API fiscal, expande o endpoint de emissão de NF-e, vê o modelo de JSON esperado e envia uma nota de teste no ambiente de homologação.
• Uma equipe de marketplace usa o Swagger UI para conferir quais query parameters o endpoint de listagem aceita para filtrar NFS-e por período e status.
• Ao receber uma rejeição fiscal, o programador reproduz a mesma requisição no Swagger UI para isolar se o problema está no payload ou no código da integração.
• Um analista de suporte usa o Swagger UI para consultar o status de um documento pela chave de acesso, sem precisar instalar nenhuma ferramenta extra.