O Swagger é uma poderosa ferramenta para documentar e testar APIs, tornando o processo de desenvolvimento mais ágil e eficiente. Quando integrado a projetos ASP.NET, ele não apenas automatiza a geração da documentação, mas também oferece uma interface gráfica interativa para explorar os endpoints da API em tempo real. Neste artigo, vamos detalhar como configurar o Swagger em projetos ASP.NET, personalizar sua documentação e facilitar a compreensão e uso da sua API por outros desenvolvedores.
Adicionando o Swagger no ASP.NET
Instalação do pacote
No Visual Studio, ao configurar uma aplicação de API em .NET, a opção de adicionar suporte ao OpenAPI (Swagger) geralmente já vem habilitada por padrão.
Porém, caso você tenha uma aplicação que não possua suporte ao Swagger e deseje implementá-lo, siga os seguintes passos:
No seu projeto ASP.NET, você precisa adicionar o pacote NuGet “Swashbuckle.AspNetCore”. Vá até Ferramentas > Gerenciador de Pacotes NuGet > Console do Gerenciador de Pacotes e execute o seguinte comando:
Install-Package Swashbuckle.AspNetCore
Isso irá adicionar o pacote necessário ao seu projeto, permitindo que você configure e utilize o Swagger para documentar sua API.
Configurando o Swagger
Agora, você precisa configurar o Swagger para que ele funcione corretamente.
No arquivo “Program.cs” (ou “Startup.cs”, dependendo da versão do ASP.NET Core), adicione o Swagger no pipeline de serviços:
builder.Services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1",
new OpenApiInfo
{
Title = "API Documentação Swagger",
Description = "Esta é uma API de ensino sobre o swagger",
Contact = new OpenApiContact
{
Name = "Next Wave Education",
Email = "email@mail.com",
Url = new Uri("https://nextwave.education/")
},
Version = "v1"
});
O “AddSwaggerGen” adiciona o serviço do Swagger no pipeline da aplicação. Dentro dessa função, o método “SwaggerDoc” é chamado para definir um documento que representará a API. Essas informações serão exibidas na interface gráfica do Swagger, facilitando a visualização e o uso da API pelos desenvolvedores. O resultado será semelhante a esse:
Ainda no arquivo “Program.cs” vamos configurar o “Swagger” e o “Swagger UI” para serem usados em um ambiente de desenvolvimento, permitindo que a documentação da API seja acessível através de uma interface gráfica.
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
O “app.UseSwagger()” ativa o middleware do Swagger, responsável por gerar um arquivo JSON contendo a documentação dos endpoints da API. Esse arquivo JSON segue o formato especificado pela OpenAPI e que vai ser utilizado pelo Swagger UI para exibir a documentação de forma legível e interativa.
O “app.UseSwaggerUI()” é responsável por configurar a interface gráfica do Swagger UI, que é a página onde os desenvolvedores podem interagir com a API.
Em nosso exemplo utilizamos a condição “if” para verificar se a aplicação está em ambiente de desenvolvimento. Se sim, deve ser apresentada a interface do swagger, caso contrário a interface não será apresentada.
Em seguida, localize a pasta “Properties” no seu projeto. Dentro dessa pasta, você encontrará o arquivo “launchSettings.json”. Abra esse arquivo e altere o valor do parâmetro “launchUrl” para “swagger”. Isso fará com que o Swagger seja carregado automaticamente como a página inicial quando você executar a aplicação.
Pronto! Agora a sua aplicação já está sendo executada com documentação feita pelo swagger.
Agora vamos para a segunda parte do nosso artigo onde vamos enriquecer a nossa documentação com detalhes que ajudam os desenvolvedores a entenderem melhor como utilizar os endpoints.
Customizando a documentação
Essa linha instrui o compilador a gerar um arquivo XML contendo todos os comentários documentados em seu código durante o processo de compilação.
builder.Services.AddSwaggerGen(c =>
{
//Configuração adicionada anteriormente da documentação do swagger.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});
Nesta parte do código, estamos configurando o Swagger para incluir a documentação gerada a partir dos comentários XML. Primeiro, criamos o nome do arquivo XML com base no nome da assembly atual. Em seguida, usamos “Path.Combine” para gerar o caminho completo desse arquivo no diretório da aplicação. Por fim, chamamos “c.IncludeXmlComments(xmlPath)” para incluir esses comentários na documentação do Swagger, garantindo que as descrições e exemplos que você escreveu no código sejam exibidos na interface do Swagger UI.
Agora na controller, acima dos métodos dos endpoints, é possível adicionar comentários para melhorar a documentação, da seguinte forma:
// Comentários aqui
[HttpGet]
public ActionResult<List<Produto>> BuscarTodos()
{
}
Summary
/// <summary>
/// Obtém todos os produtos.
/// </summary>
O <summary> é utilizado para fornecer uma descrição concisa do que o método faz. Neste caso, a explicação é: “Obtém todos os produtos”.
Resultado na interface:
Remarks
/// <remarks>
/// Retorno:
///
/// GET /Produtos
/// {
/// "id": 1,
/// "nome": "Cadeira",
/// "valor": 999
/// }
/// </remarks>
Na seção <remarks>, podemos adicionar um exemplo do retorno esperado ou descrever como os dados devem ser enviados ou recebidos. No exemplo acima, mostramos a estrutura dos dados que serão retornados em formato JSON.
Resultado na interface:
Response
/// <response code="201">Retorna uma lista de itens de Produtos quando a requisição tem sucesso.</response>
/// <response code="400">Se encontrar um erro.</response>
Os comentários <response> especificam os códigos de resposta que o método pode retornar, junto com uma breve descrição. Aqui usamos:
- 201 (Created): indica que a requisição foi bem-sucedida e retornou a lista de produtos.
- 400 (Bad Request): indica que houve um erro na requisição, por exemplo, devido a dados inválidos.
Os atributos [ProducesResponseType] devem ser colocados logo abaixo do método http (ex: HttpGet) e servem para declarar os códigos de resposta suportados pelo endpoint. No exemplo abaixo, indicamos que o método pode retornar os status 201 Created e 400 Bad Request.
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
Resultado na interface:
Configurando autenticação na UI do Swagger com JWT
Uma funcionalidade importante para garantir segurança em suas APIs é a autenticação, e no caso de APIs que utilizam tokens JWT, o Swagger permite que você insira o token diretamente na interface para realizar testes nos endpoints protegidos. Vamos ver como configurar isso.
Para configurar a autenticação JWT no Swagger, adicione o seguinte código dentro da configuração do “SwaggerGen” no arquivo “Program.cs”:
builder.Services.AddSwaggerGen(c =>
{
c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
Name = "Authorization",
Type = SecuritySchemeType.Http,
Scheme = "Bearer",
BearerFormat = "JWT",
In = ParameterLocation.Header,
Description = "Insira o token JWT no campo abaixo.",
});
});
O método “AddSecurityDefinition” é utilizado para definir como o Swagger deve lidar com o mecanismo de autenticação.
– “Bearer”: esse é o identificador do esquema de autenticação que será usado no Swagger.
O método “OpenApiSecurityScheme” completa o esquema de segurança que descreve como o token JWT será passado para a API.
Name = “Authorization”: define o nome do cabeçalho HTTP onde o token será enviado. No caso de autenticação JWT, o cabeçalho Authorization é utilizado para passar o token junto à requisição.
Type = SecuritySchemeType.Http: o tipo de segurança é definido como HTTP, já que estamos utilizando um cabeçalho HTTP para passar o token.
Scheme = “Bearer”: o esquema é definido como “Bearer”, que é o padrão utilizado para autenticação baseada em tokens JWT. Isso significa que o token será precedido pela palavra “Bearer” no cabeçalho da requisição. Ou seja, quando for adicionar o token não é necessário colocar a palavra “Bearer” antes, pois ela será adicionada automaticamente.
BearerFormat = “JWT”: Define o formato do token, que no nosso caso é JWT (JSON Web Token).
In = ParameterLocation.Header: especifica onde o token será inserido na requisição. Aqui, estamos indicando que ele deve ser passado no cabeçalho da requisição HTTP.
Description = “Insira o token JWT no campo abaixo.”: É a descrição que será exibida na interface gráfica do Swagger para orientar o desenvolvedor sobre como inserir o token.
Após definir o esquema de segurança, é necessário especificar que ele será aplicado a todos ou a determinados endpoints da API. Então, ainda dentro do “SwaggerGen”, vamos adicionar uma segunda configuração:
c.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type = ReferenceType.SecurityScheme,
Id = "Bearer"
}
},
new string[] {}
}
});
Vamos entender cada parte dessa configuração:
new OpenApiSecurityScheme { … }: Estamos criando uma nova instância de um esquema de segurança, que faz referência ao esquema que já definimos anteriormente, chamado “Bearer”.
Reference = new OpenApiReference { … }: Aqui, estamos informando ao Swagger que o esquema de segurança que vamos usar já foi previamente definido. Em vez de recriá-lo, apenas referenciamos o existente.
Type = ReferenceType.SecurityScheme: Esse parâmetro especifica que estamos nos referindo a um esquema de segurança.
Id = “Bearer”: O ID usado é “Bearer”, que corresponde ao esquema de autenticação JWT que configuramos anteriormente. Isso garante que o Swagger aplique as regras de autenticação baseadas no token JWT.
new string[] {}: Esse array vazio indica que não estamos definindo escopos adicionais de autenticação. Escopos são frequentemente usados em OAuth para especificar permissões, mas como não estamos utilizando escopos aqui, deixamos o array vazio.
Essa configuração é importante porque faz com que o Swagger aplique o esquema de segurança JWT aos endpoints da API. Dessa forma, sempre que um desenvolvedor for testar um endpoint protegido, o Swagger irá solicitar que o token JWT seja incluído, garantindo que as requisições sejam autenticadas corretamente.
Ao executar a aplicação, você verá um botão de autorização no Swagger. Esse botão permite adicionar o token JWT, que será usado automaticamente nas próximas requisições feitas aos endpoints da API.
Acelere a sua carreira conosco!
Se você é Desenvolvedor .NET Júnior e quer acelerar sua carreira até nível Pleno com salário de R$7k+, ou mesmo busca a primeira vaga, conheça a Mentoria .NET Start: Clique aqui Se é Desenvolvedor .NET Pleno ou Sênior e quer virar referência técnica em sua equipe e mercado, com salário de R$10k+, conheça a Mentoria .NET Expert: Clique aquiConclusão
A integração do Swagger com ASP.NET oferece uma maneira eficaz de documentar suas APIs, proporcionando uma interface interativa para testes e uma documentação clara para desenvolvedores. Com as opções de personalização disponíveis, você pode adaptar a documentação às suas necessidades específicas, garantindo que sua API seja fácil de entender e utilizar.