APIs com ASP.NET Core

32 - Swagger

Olá pessoal, nessa trigésima segunda aula do treinamento de Criando APIs com ASP.NET Core, vamos aprender a trabalhar com o Swagger.

O Swagger serve para documentarmos nossas APIs, especificando as rotas e também as entidades disponíveis. Também é possível realizar testes em nossas APIs, fazendo com que o Thunder Client não precise ser utilizado.

Podemos trabalhar com o Swagger em várias tecnologias, como por exemplo: Spring (Java e Kotlin), PHP, Python, etc...

Para efetuarmos o uso do Swagger é muito simples, siga os passos abaixo:

1º Instale o pacote do Swagger: dotnet add package Swashbuckle.AspNetCore.Swagger --version 6.8.1

2º Vamos implementar o arquivo Program.cs:

// Importar OpenApi
using Microsoft.OpenApi.Models;

// Cria e configura o objeto `WebApplicationBuilder`, que é usado para configurar os serviços e o pipeline de solicitação HTTP.
var builder = WebApplication.CreateBuilder(args);

// Configuração de CORS
builder.Services.AddCors(options =>
{
    options.AddPolicy("ConfigurarCORS", builder =>
    {
        builder.AllowAnyOrigin()  // Permite qualquer origem
               .AllowAnyMethod()  // Permite qualquer método (GET, POST, etc.)
               .AllowAnyHeader(); // Permite qualquer cabeçalho
    });
});

// Configura os serviços necessários para a aplicação. 
// `AddControllers` adiciona suporte para controllers MVC, o que permite criar endpoints de API e renderizar views.
builder.Services.AddControllers();

// Configura o Swagger
// AddEndpointsApiExplorer: permite a geração automática de documentação para endpoints da API.
builder.Services.AddEndpointsApiExplorer();

// AddSwaggerGen: adiciona os serviços necessários para gerar a documentação do Swagger.
builder.Services.AddSwaggerGen(c =>
{
    // Define um documento Swagger chamado "v1"
    c.SwaggerDoc("v1", new OpenApiInfo 
    { 
        Title = "Minha API", // Título da API
        Version = "v1",      // Versão da API
        Description = "Uma API para gerenciar um CRUD de pessoas." // Descrição da API
    });
});

// Obtém a string de conexão para o banco de dados a partir da configuração do aplicativo.
// Se a string de conexão 'DefaultConnection' não for encontrada, uma exceção é lançada para indicar que a configuração está ausente.
var stringDeConexao = builder.Configuration.GetConnectionString("DefaultConnection") ?? throw new InvalidOperationException("A string de conexão 'DefaultConnection' não foi encontrada.");

// Registra o repositório `PessoaRepositorio` como um serviço singleton no contêiner de injeção de dependência.
// Um singleton garante que apenas uma instância do repositório será criada e usada em toda a aplicação.
builder.Services.AddSingleton(new PessoaRepositorio(stringDeConexao));

// Constrói o objeto `WebApplication` com base nas configurações fornecidas e no contêiner de serviços configurado.
var app = builder.Build();

// Aplicar a política de CORS
app.UseCors("ConfigurarCORS");

// Configura o Swagger UI
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    // Define a rota onde o Swagger JSON estará disponível
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Minha API V1");
    
    // Define a rota do Swagger UI como a raiz do aplicativo
    c.RoutePrefix = "swagger"; // Assim, você acessa o Swagger UI em http://localhost:<porta>
});

// Mapeia os controllers para os endpoints disponíveis na aplicação.
// Isso faz com que os controllers sejam acessíveis através das rotas definidas nas suas classes de controller.
app.MapControllers();

// Inicia a aplicação e começa a escutar as solicitações HTTP.
app.Run();

Pronto! Com essas duas etapas, podemos atualizar nosso servidor (CTRL + R) e acessar a rota, exemplo: localhost:5081/swagger.

Complemento

Muitos inscritos pedem materiais complementares sobre o Swagger, então darei algumas dicas abaixo de anotações utilizadas e também como implementar no arquivo de rotas:

[SwaggerOperation]
- Purpose: Adiciona informações de resumo e descrição para cada operação no Swagger. Essas informações aparecem na documentação da API para que os desenvolvedores saibam o propósito de cada endpoint.
- Properties:
  - Summary: Breve descrição da operação (ex: "Cadastrar uma nova pessoa").
  - Description: Descrição mais detalhada da operação (ex: "Esta rota permite cadastrar uma nova pessoa fornecendo as informações como nome, cidade e idade.")
[SwaggerResponse]
- Purpose: Define as respostas possíveis para uma operação, incluindo o código de status HTTP e o tipo de conteúdo retornado. Ajuda a documentar os resultados possíveis de uma rota na documentação Swagger.
- Properties:
  - HTTP Status Code: O código de status HTTP que será retornado (ex: 200, 201, 400, 404).
  - Response Type: O tipo de dado esperado na resposta (por exemplo, um objeto de tipo `Pessoa`, ou um tipo genérico como `string`).
[FromBody]
- Purpose: Indica que o parâmetro de um método (como o modelo `Pessoa`) será passado no corpo da requisição HTTP (request body). É usado para parâmetros que precisam ser deserializados de JSON, por exemplo.
- Example: No método `Cadastrar([FromBody] Pessoa p)`, o objeto `Pessoa` é passado no corpo da requisição.
[FromRoute]
- Purpose: Indica que o valor do parâmetro será extraído da URL da rota (no caminho da URL). Este é o caso para parâmetros como um ID de recurso (ex: `codigo` na rota de alteração ou remoção).
- Example: No método `Alterar(int codigo)`, o `codigo` é passado como parte da URL (ex: `/pessoa/{codigo}`).
[Required]
- Purpose: Indica que o campo é obrigatório e não pode ser `null` ou vazio. Usado no modelo `Pessoa` para garantir que certos campos, como `Nome` e `Cidade`, sejam fornecidos.
- Example: `[Required] public string Nome { get; set; }` no modelo `Pessoa` assegura que o nome não seja nulo ou vazio.
[StringLength]
- Purpose: Restringe o comprimento de uma string a um valor máximo ou mínimo. Pode ser útil para garantir que campos como `Nome` não ultrapassem um certo número de caracteres.
- Example: `[StringLength(100)] public string Nome { get; set; }` limita o campo `Nome` a no máximo 100 caracteres.
[Range]
- Purpose: Define um intervalo válido de valores para um campo numérico, como a idade, que precisa estar entre 0 e 120.
- Example: `[Range(0, 120)] public int Idade { get; set; }` garante que a idade esteja dentro do intervalo de 0 a 120.

Vamos ver na prática? Veja como fica nosso arquivo de controle com as data annotations acima:

// Importações
using Microsoft.AspNetCore.Mvc;
using Swashbuckle.AspNetCore.Annotations;

[ApiController]
[Route("pessoa")]
public class PessoaControle : ControllerBase
{
    private readonly PessoaRepositorio _pessoaRepositorio;

public PessoaControle(PessoaRepositorio pessoaRepositorio)
    {
        _pessoaRepositorio = pessoaRepositorio;
    }

// Rota de cadastro
    [HttpPost]
    [SwaggerOperation(
        Summary = "Cadastrar uma nova pessoa",
        Description = "Esta rota permite cadastrar uma nova pessoa fornecendo as informações como nome, cidade e idade."
    )]
    [SwaggerResponse(201, "Pessoa cadastrada com sucesso.", typeof(Pessoa))]
    [SwaggerResponse(400, "Erro na validação dos dados fornecidos.")]
    public IActionResult Cadastrar([FromBody] Pessoa p)
    {
        if (string.IsNullOrEmpty(p.Nome))
        {
            return BadRequest(new { mensagem = "O nome é obrigatório!" });
        }
        else if (string.IsNullOrEmpty(p.Cidade))
        {
            return BadRequest(new { mensagem = "A cidade é obrigatória!" });
        }
        else if (p.Idade < 0 || p.Idade > 120)
        {
            return BadRequest(new { mensagem = "A idade precisa estar entre 0 e 120!" });
        }
        else
        {
            var obj = _pessoaRepositorio.CadastrarPessoa(p);
            return Created(string.Empty, obj);
        }
    }

// Rota de seleção
    [HttpGet]
    [SwaggerOperation(
        Summary = "Selecionar todas as pessoas cadastradas",
        Description = "Recupera a lista de todas as pessoas cadastradas no sistema."
    )]
    [SwaggerResponse(200, "Lista de pessoas", typeof(List<Pessoa>))]
    public List<Pessoa> Selecionar()
    {
        return _pessoaRepositorio.SelecionarPessoas();
    }

// Rota de alteração
    [HttpPut("{codigo}")]
    [SwaggerOperation(
        Summary = "Alterar os dados de uma pessoa existente",
        Description = "Altera os dados de uma pessoa com base no código fornecido."
    )]
    [SwaggerResponse(200, "Pessoa alterada com sucesso.", typeof(Pessoa))]
    [SwaggerResponse(400, "Erro na validação dos dados fornecidos.")]
    [SwaggerResponse(404, "Pessoa não encontrada.")]
    public IActionResult Alterar(int codigo, [FromBody] Pessoa p)
    {
        if (!_pessoaRepositorio.ExistePessoa(codigo))
        {
            return NotFound(new { mensagem = "O código informado não existe!" });
        }

if (string.IsNullOrEmpty(p.Nome))
        {
            return BadRequest(new { mensagem = "O nome é obrigatório!" });
        }
        else if (string.IsNullOrEmpty(p.Cidade))
        {
            return BadRequest(new { mensagem = "A cidade é obrigatória!" });
        }
        else if (p.Idade < 0 || p.Idade > 120)
        {
            return BadRequest(new { mensagem = "A idade precisa estar entre 0 e 120!" });
        }

p.Codigo = codigo;
        _pessoaRepositorio.AlterarPessoa(p);

return Ok(p);
    }

// Rota de remoção
    [HttpDelete("{codigo}")]
    [SwaggerOperation(
        Summary = "Remover uma pessoa do sistema",
        Description = "Remove a pessoa com o código fornecido."
    )]
    [SwaggerResponse(200, "Pessoa removida com sucesso.")]
    [SwaggerResponse(404, "Pessoa não encontrada.")]
    public IActionResult Remover(int codigo)
    {
        if (_pessoaRepositorio.ExistePessoa(codigo))
        {
            _pessoaRepositorio.RemoverPessoa(codigo);
            return Ok(new { mensagem = "Pessoa removida com sucesso!" });
        }
        else
        {
            return NotFound(new { mensagem = "Código não encontrado!" });
        }
    }
}

Acompanhe a aula abaixo, onde ensino como implementar essa etapa do treinamento.

Torne-se membro! a partir de R$7,99 por mês.

Abaixo compartilho o vídeo da nossa aula no YouTube, bons estudos!