Resumo

OpenAPI/Swagger gera documentação interativa da API. Integramos o Swashbuckle, adicionamos suporte a autorização JWT na UI e enriquecemos a documentação com metadados e comentários XML.

1. Objetivos de Aprendizagem#

Integrar Swagger/OpenAPI ao projeto.
Configurar o botão de autorização (Bearer) na Swagger UI.
Estender a documentação com título, versão e comentários XML.

2. Pré-requisitos#

Autenticação JWT (Módulo 40).

3. Conceito#

OpenAPI é um padrão para descrever APIs REST; Swagger é o ecossistema de ferramentas (UI, geração). O porquê: documentação viva, testável no navegador, e base para gerar SDKs de clientes.

Nota

no template atual do .NET 9, dotnet new webapi inclui Microsoft.AspNetCore.OpenAPI (AddOpenApi/MapOpenApi) para gerar o documento OpenAPI, mas não inclui uma UI. Para a UI clássica do Swagger, usamos o pacote Swashbuckle.

4. Mão na Massa#

4.1. Setup#

Shell

dotnet add Catalog.Api package Swashbuckle.AspNetCore

Habilite comentários XML no .csproj:

XML

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

4.2. Implementação Passo a Passo#

Registro com metadados e segurança:

builder.Services.AddSwaggerGen(s =>
{
    s.SwaggerDoc("v1", new() { Title = "Catalog API", Version = "v1" });

    var xml = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
    s.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xml));

    s.AddSecurityDefinition("Bearer", new()
    {
        In = ParameterLocation.Header,
        Description = "Insira: Bearer {seu token}",
        Name = "Authorization",
        Type = SecuritySchemeType.ApiKey,
        Scheme = "Bearer"
    });
    s.AddSecurityRequirement(new()
    {
        {
            new() { Reference = new() { Type = ReferenceType.SecurityScheme, Id = "Bearer" } },
            Array.Empty<string>()
        }
    });
});

Pipeline (apenas em Development, por padrão):

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(o => o.SwaggerEndpoint("/swagger/v1/swagger.json", "Catalog API v1"));
}

Documente ações com comentários XML e ProducesResponseType:

/// <summary>Retorna todos os produtos.</summary>
/// <response code="200">Lista de produtos.</response>
[HttpGet]
[ProducesResponseType(typeof(IEnumerable<ProdutoDto>), StatusCodes.Status200OK)]
public async Task<IActionResult> Get() => Ok(await _service.Produto.GetAllAsync(false));

4.3. Executando#

Shell

dotnet run
# abra http://localhost:5000/swagger

5. Exemplo Completo#

Com o AddSecurityDefinition, a Swagger UI ganha o botão Authorize para colar o token JWT e testar endpoints protegidos direto do navegador.

6. Boas Práticas e Armadilhas#

Faça	Evite
Documentar respostas com `ProducesResponseType`	Deixar a doc sem status codes/DTOs
Expor a UI só em ambientes apropriados	Deixar Swagger UI aberto em produção sem controle
Incluir comentários XML	Documentação vazia gerada só pela assinatura

Atenção

expor a Swagger UI publicamente em produção revela toda a superfície da API. Se necessário em produção, proteja-a (autenticação/rede interna).

7. Segurança e Produção#

A documentação pode revelar endpoints sensíveis; controle o acesso em ambientes públicos.
Não inclua exemplos com segredos reais na documentação.

8. Exercícios#

Fácil: adicione título e descrição ao documento OpenAPI.
Médio: documente os códigos 401/403 nos endpoints protegidos.
Desafio: gere documentação separada por versão de API (Módulo 37).

9. Resumo#

Swagger/OpenAPI gera documentação interativa; configuramos o botão Authorize para JWT e enriquecemos com XML e ProducesResponseType. Em produção, exposição deve ser controlada.

10. Próximos Passos#

Módulo 43: deploy da aplicação no IIS.

11. Referências#

Microsoft Learn — Documentação OpenAPI no ASP.NET Core
Documentação — Swashbuckle.AspNetCore
Microsoft Learn — Suporte a OpenAPI no .NET 9