Tiago Crizanto

Atualizando Swagger da versão 8 para a 10

Manter pacotes nuget atualizados é uma tarefa meio que entediante, repetitiva e muitas vezes dá muita dor de cabeça por conta de breaking changes e dependencias de outros pacotes. Mas infelizmente é uma tarefa necessária por conta de segurança e atualizações sistemicas.

Se você chegou até este post então o swagger não é novidade para você, por isso, nem vou entrar nos detalhes deste pacote, afinal, um bom google ou qualquer IA pode explicar isso de forma rápida. O objetivo do post aqui é mostrar como fazer a atualização da versão 8 do swagger para a 10, pois, houve breaking changes e alguns namespaces foram atualizados e classes como OpenApiReference não estão mais disponíveis.

Quando precisei fazer a atualização não encontrei algo prático que mostrasse onde houve atualizações, então resolvi colocar isso em um post porque além de precisar com frequencia pode ajudar outras pessoas.

Se o seu projeto está utilizando dotnet core provavelmente você tem alguns destes pacotes instalados:
– Asp.Versioning.Mvc.ApiExplorer
– Swashbuckle.AspNetCore
– Swashbuckle.AspNetCore.Annotations
– Swashbuckle.AspNetCore.SwaggerGen

Aqui está a configuração do swagger antes da atualização feita no arquivo Program.cs

using Microsoft.OpenApi.Models;

builder.Services.AddSwaggerGen(option =>
{
    option.SwaggerDoc("v1", new OpenApiInfo { Title = "Swagger API Title", Version = "v1" });
    option.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        In = ParameterLocation.Header,
        Description = "",
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        BearerFormat = "JWT",
        Scheme = "Bearer"
    });
    option.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type=ReferenceType.SecurityScheme,
                    Id="Bearer"
                }
            },
            Array.Empty<string>()
        }
    });
});

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI();

Ao atualizar os pacotes para a última versão alguns namespaces como Microsoft.OpenApi.Models não estão mais disponíveis e algumas classes de configuração tiveram alterações como a OpenApiSecurityScheme. Isso exige alterar a configuração do swagger no Program.cs que ficou assim:

using Microsoft.OpenApi;

builder.Services.AddSwaggerGen(option =>
{
    option.SwaggerDoc("v1", new OpenApiInfo { Title = "Swagger API Title", Version = "v1" });
    option.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        In = ParameterLocation.Header,
        Description = "Please enter a valid token",
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        BearerFormat = "JWT",
        Scheme = "Bearer"
    });
    option.AddSecurityRequirement(document => new OpenApiSecurityRequirement
    {
        [new OpenApiSecuritySchemeReference("Bearer", document)] = []
    });
});

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI();

Como pode-se notar o método AddSecurityRequirement agora é configurado de forma diferente e apenas com estas alterações você já consegue compilar o seu projeto e deixar tudo rodando.

Lembrando que esta é uma configuração básica que é utilizada em muitos projetos que não requerem muita customização. Esse código pode servir de base para você mesmo se o seu projeto possui configurações mais avançadas.