1. OpenAPI vs. Swagger — os nomes que causam confusão
OpenAPI é a especificação — um formato JSON/YAML padronizado que descreve todos os endpoints de uma API: rotas, parâmetros, formatos de request/response, códigos de status possíveis. Swagger é o conjunto de ferramentas (originalmente de onde a especificação nasceu) que lê esse documento e gera uma interface visual navegável. Na prática, o ASP.NET Core gera o documento OpenAPI automaticamente a partir do seu código.
2. Habilitando no projeto
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(opcoes =>
{
opcoes.SwaggerDoc("v1", new OpenApiInfo
{
Title = "API de Pedidos",
Version = "v1",
Description = "API do sistema de pedidos construído sobre o Módulo 2"
});
});
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI(); // interface visual em /swagger
}
Restringir UseSwaggerUI() a IsDevelopment()
é uma boa prática comum — expor a documentação completa da API (incluindo endpoints internos)
publicamente em produção pode dar a um atacante um mapa completo da sua superfície de ataque.
3. Enriquecendo a documentação gerada
Sem nenhuma anotação extra, o Swagger já descobre rotas, verbos e tipos a partir da assinatura dos seus métodos. Atributos e comentários XML deixam a documentação mais completa:
/// <summary>
/// Busca um cliente pelo Id.
/// </summary>
/// <param name="id">Identificador único do cliente</param>
/// <response code="200">Cliente encontrado</response>
/// <response code="404">Cliente não existe</response>
[HttpGet("{id:int}")]
[ProducesResponseType(typeof(ClienteDto), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<ActionResult<ClienteDto>> ObterPorId(int id) { ... }
Para os comentários /// aparecerem no Swagger, é preciso habilitar a
geração do arquivo XML de documentação no .csproj:
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>4. Documentando autenticação JWT no Swagger
Para testar endpoints protegidos (capítulo anterior) direto na interface do Swagger, é preciso ensiná-lo sobre o esquema de autenticação:
builder.Services.AddSwaggerGen(opcoes =>
{
opcoes.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
Name = "Authorization",
Type = SecuritySchemeType.Http,
Scheme = "Bearer",
BearerFormat = "JWT",
In = ParameterLocation.Header,
Description = "Informe: Bearer {seu token}"
});
opcoes.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer" }
},
Array.Empty<string>()
}
});
});Com isso, a interface do Swagger ganha um botão "Authorize" onde você cola o token — e ele passa a ser enviado automaticamente em toda chamada de teste feita pela interface.
5. Onde isso te leva
Com a API documentada e testável, o próximo capítulo cobre o que acontece quando algo dá errado de forma inesperada — tratamento global de exceções, para que nenhum erro não tratado vaze detalhes internos (stack trace, string de conexão) para quem consome a API.