¶ 1. Visão Geral
O Swagger é uma ferramenta que facilita a criação, documentação e consumo de APIs (Application Programming Interface). Ele fornece uma interface interativa que permite aos desenvolvedores e consumidores externos visualizar, testar e interagir com os endpoints de uma API de maneira intuitiva. Através do Swagger, é possível gerar automaticamente a documentação da API a partir do código-fonte, garantindo que a documentação esteja sempre atualizada e em sincronia com as implementações. Além disso, o Swagger suporta uma ampla gama de linguagens de programação e frameworks.
¶ 2. Autenticação e Autorização
O Swagger fica acessível por padrão apenas em ambiente de desenvolvimento. Para ambientes de produção, a habilitação é opcional via configuração.
Comportamento
| Ambiente | Parâmetro SwaggerEnabled | Usuário Autenticado | Resultado |
|---|---|---|---|
| Desenvolvimento | N/A | Sim | ✓ Acesso concedido |
| Desenvolvimento | N/A | Não | 401 Unauthorized |
| Produção | false (padrão) | Sim/Não | 403 Forbidden |
| Produção | true | Sim | ✓ Acesso concedido |
| Produção | true | Não | 401 Unauthorized |
- Retorna 403 (Forbidden) quando o Swagger está desabilitado para o ambiente.
- Retorna 401 (Unauthorized) quando o usuário não está autenticado.
Como habilitar em produção
Inclua a configuração no arquivo appsettings.json:
{
"SwaggerEnabled": true
}
- Em ambientes de produção, o padrão é false.
Temos algumas formas de autenticação dentro do Swagger, as normalmente utilizadas são:
- Basic: Autorização utilizando usuário e senha, separados por ":" convertidos em Base64.
- Bearer: É um Schema que utiliza um Token do tipo JWT (JSON Web Token) que autoriza o usuário a acessar as APIs.
- OAuth 2: É um protocolo de autorização via Token.
¶ 3. Utilização
Para abrir o Swagger, iremos utilizar o endpoint: URL.../swagger/index.html
- Exemplo de endpoint em ambiente cloud:
qablue.tech6cloud.com/swagger/index.html(neste caso,qablueé o nome do seu domínio). - Exemplo de endpoint em ambiente local:
(servidor do IIS)/(nome da aplicação no IIS)/swagger/index.html
A URL informada antes da API vai depender do seu domínio na cloud, ou, em caso de ambiente local, das configurações informadas no seu IIS (Internet Information Services).
Ao acessar o endpoint será aberta uma página contendo todas as APIs do sistema, clique em 
para expandir a API selecionada.
- Serão exibidos os parâmetros necessários para a execução da API e também as possíveis respostas que o sistema pode lhe retornar, assim como uma exibição detalhada da requisição. Para habilitar a inserção dos parâmetros e executar a API, clique em "Try it out"
- Ao clicar em "Try it out" será habilitada a inserção de dados nos parâmetros, além da exibição do botão "Execute", que fará a execução da API conforme os parâmetros inseridos
- Ao executar a API, o Swagger irá devolver uma resposta com o código e a descrição, informando quanto ao sucesso ou falha na execução. Em caso de falha, irá devolver detalhadamente o código de erro e o motivo da falha
Para mais informações e formas de consumir as APIs, acesse nossa central de ajuda: Data Integration
¶ 4. Q&A
Perguntas Frequentes
1. Como acessar o Swagger em ambiente de produção?
Para acessar o Swagger em ambiente de produção, é necessário habilitar a configuração no arquivo appsettings.json, definindo "SwaggerEnabled": true. Por padrão, o Swagger está desabilitado em produção por questões de segurança.
2. Por que recebo erro 403 (Forbidden) ao tentar acessar o Swagger?
O erro 403 (Forbidden) indica que o Swagger está desabilitado para o ambiente atual. Em ambientes de produção, o Swagger precisa ser explicitamente habilitado através da configuração "SwaggerEnabled": true no arquivo appsettings.json.
3. Por que recebo erro 401 (Unauthorized) ao acessar o Swagger?
O erro 401 (Unauthorized) significa que você não está autenticado no sistema. É necessário fazer login na aplicação antes de acessar o Swagger, independentemente do ambiente (desenvolvimento ou produção).
4. Quais são os métodos de autenticação disponíveis no Swagger?
O Swagger suporta três métodos principais de autenticação:
- Basic: Utiliza usuário e senha separados por ":" e convertidos em Base64.
- Bearer: Utiliza um Token JWT (JSON Web Token) para autorização.
- OAuth 2: Protocolo de autorização via Token.
5. Como executar uma API através do Swagger?
Para executar uma API no Swagger:
- Clique na API desejada para expandi-la.
- Clique no botão "Try it out".
- Preencha os parâmetros necessários.
- Clique no botão "Execute".
- Visualize a resposta retornada pelo sistema.
6. Qual é a URL padrão para acessar o Swagger?
A URL padrão segue o formato: URL.../swagger/index.html. Em ambiente cloud, seria algo como seudominio.tech6cloud.com/swagger/index.html. Em ambiente local, depende da configuração do IIS: (servidor do IIS)/(nome da aplicação no IIS)/swagger/index.html.
7. O que significa a resposta que o Swagger retorna após executar uma API?
A resposta do Swagger inclui um código de status HTTP e uma descrição. Códigos 2xx indicam sucesso, enquanto códigos 4xx ou 5xx indicam erros. Em caso de falha, o Swagger fornece detalhes sobre o código de erro e o motivo da falha.
8. A documentação do Swagger é atualizada automaticamente?
Sim, o Swagger gera automaticamente a documentação da API a partir do código-fonte, garantindo que a documentação esteja sempre atualizada e em sincronia com as implementações realizadas.
9. É seguro deixar o Swagger habilitado em produção?
O Swagger expõe informações sobre a estrutura e endpoints da sua API. Por questões de segurança, ele vem desabilitado por padrão em produção. Habilite-o apenas se houver necessidade específica e certifique-se de que apenas usuários autenticados possam acessá-lo.
10. Posso testar todas as APIs do sistema através do Swagger?
Sim, o Swagger exibe todas as APIs disponíveis no sistema, permitindo visualizar, testar e interagir com cada endpoint de forma interativa. É uma ferramenta completa para desenvolvedores e consumidores externos testarem as funcionalidades da API.