ASP.NET Core – Swagger API Versioning

前言

当 Swagger 遇上 Versioning 是会直接报错的哦. 

幸好解决方法也不难. 做一些小配置就可以了

主要参考

Integrating ASP.NET Core Api Versions with Swagger UI

What every ASP.NET Core Web API project needs - Part 2 - API versioning and Swagger

安装 Versioning.ApiExplorer

dotnet add package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

Program.cs

builder.Services.AddApiVersioning(options => {
    options.ReportApiVersions = true;
});
builder.Services.AddVersionedApiExplorer(setup =>
{
    setup.GroupNameFormat = "'v'VVV";
    setup.SubstituteApiVersionInUrl = true;
});

做一个 ConfigureSwaggerOptions

public class ConfigureSwaggerOptions
      : IConfigureNamedOptions<SwaggerGenOptions>
{
    private readonly IApiVersionDescriptionProvider provider;

    public ConfigureSwaggerOptions(
        IApiVersionDescriptionProvider provider)
    {
        this.provider = provider;
    }

    public void Configure(SwaggerGenOptions options)
    {
        foreach (var description in provider.ApiVersionDescriptions)
        {
            options.SwaggerDoc(
                description.GroupName,
                CreateVersionInfo(description));
        }
    }

    public void Configure(string name, SwaggerGenOptions options)
    {
        Configure(options);
    }

    private OpenApiInfo CreateVersionInfo(
            ApiVersionDescription description)
    {
        var info = new OpenApiInfo()
        {
            Title = "Heroes API",
            Version = description.ApiVersion.ToString()
        };

        if (description.IsDeprecated)
        {
            info.Description += " This API version has been deprecated.";
        }

        return info;
    }
}

配置进去

builder.Services.AddSwaggerGen();
builder.Services.ConfigureOptions<ConfigureSwaggerOptions>();

最后是 UI, 需要注入 IApiVersionDescriptionProvider apiVersionDescriptionProvider

app.UseSwaggerUI(options =>
{
    foreach (var description in apiVersionDescriptionProvider.ApiVersionDescriptions)
    {
        options.SwaggerEndpoint(
            $"/swagger/{description.GroupName}/swagger.json",
            description.GroupName.ToUpperInvariant());
    }
});

这样就可以了