默认为 Swagger UI 上的最新 API 版本

Question

我在 API 中实现了 Swashbuckle.AspNetCore.SwaggerUI（版本 6.1.4）。 API 还配置了 Microsoft.AspNetCore.Mvc.Versioning（版本 5.0.0）。

现在可以使用了，我可以在页面顶部设置 API 版本来解析各种公开的端点。

我的问题是，我能否将 Swagger UI 配置为将 Swagger 页面右上角的版本下拉列表默认为最高 API 版本。目前显示如下：

Select a definition - V1.0 (default)
                      V1.1
                      V2.0

我希望 UI 为默认值，在本例中为最新发布的版本 (V2.0)

这是我的代码：

        services.AddTransient<IConfigureOptions<SwaggerGenOptions>, SwaggerOptions>();

        services.AddSwaggerGen(
            options =>
            {
                options.EnableAnnotations();
                var xmlCommentsPath = GetXmlCommentsFilePath();
                if (File.Exists(xmlCommentsPath))
                {
                    options.IncludeXmlComments(xmlCommentsPath);
                }

                options.AddSecurityDefinition(
                    "Bearer", new OpenApiSecurityScheme
                    {
                        Name = "Authorization",
                        Type = SecuritySchemeType.ApiKey,
                        Scheme = "Bearer",
                        BearerFormat = "JWT",
                        In = ParameterLocation.Header,
                        Description = "JWT Authorization header using the Bearer scheme."
                    });

                options.AddSecurityRequirement(
                    new OpenApiSecurityRequirement
                    {
                        {
                            new OpenApiSecurityScheme
                            {
                                Reference = new OpenApiReference
                                {
                                    Type = ReferenceType.SecurityScheme,
                                    Id = "Bearer"
                                }
                            },
                            Array.Empty<string>()
                        }
                    });
            });

public class SwaggerOptions : IConfigureOptions<SwaggerGenOptions>
{
    private readonly IApiVersionDescriptionProvider provider;


    /// <summary>
    /// Initializes a new instance of the <see cref="SwaggerOptions"/> class.
    /// </summary>
    /// <param name="provider">The <see cref="IApiVersionDescriptionProvider">provider</see> used to generate Swagger documents.</param>
    public SwaggerOptions(
        IApiVersionDescriptionProvider provider)
    {
        this.provider = provider;
    }


    /// <inheritdoc />
    public void Configure(
        SwaggerGenOptions options)
    {
        // add a swagger document for each discovered API version
        // note: you might choose to skip or document deprecated API versions differently
        foreach (var description in provider.ApiVersionDescriptions)
        {
            options.SwaggerDoc(description.GroupName, CreateInfoForApiVersion(description));
        }
    }


    private static OpenApiInfo CreateInfoForApiVersion(
        ApiVersionDescription description)
    {
        var info = new OpenApiInfo
        {
            Title = "Demo API",
            Version = description.ApiVersion.ToString(),
            Description = "A sample application with Swagger, Swashbuckle, and API versioning.",
            Contact = new OpenApiContact {Name = "DemoApi"},
            License = new OpenApiLicense {Name = "MIT", Url = new Uri("https://opensource.org/licenses/MIT")}
        };

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

        return info;
    }
}

public static class SwaggerConfigExtension
{
    public static IApplicationBuilder
        ConfigureSwaggerUi(
            this IApplicationBuilder app,
            IApiVersionDescriptionProvider apiVersionProvider)
    {
        return app.UseSwaggerUI(
            options =>
            {
                options.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.Full);
                foreach (var description in apiVersionProvider.ApiVersionDescriptions)
                {
                    options.SwaggerEndpoint(
                        $"/swagger/{description.GroupName}/swagger.json",
                        description.GroupName.ToUpperInvariant());
                }
            }
        );
    }
}

任何 help/direction 将不胜感激。

Answer 1

安装 nuget Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

然后在Startup.cs

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env, IApiVersionDescriptionProvider apiVersionDescriptionProvider)
    {
.....

    app.UseSwaggerUI(c =>
            {
                foreach (var description in apiVersionDescriptionProvider.ApiVersionDescriptions.Reverse())
                {
                    // Create the Swagger endpoints for each version
                    c.SwaggerEndpoint($"/swagger/" +
                        $"LibraryOpenAPISpecification{description.GroupName}/swagger.json",
                        description.GroupName.ToUpperInvariant());
                }
                c.RoutePrefix = ""; // swagger UI at the root index.html
            });
....
}

看到这个答案：

Answer 2

在我的例子中，我只需要对从 IApiVersionDescriptionProvider 返回的 SwaggerConfigExtension 方法中的值进行排序。这是我的代码，Swagger 下拉列表按降序（最新到最旧）顺序显示版本。

public static class SwaggerConfigExtension
{
    public static IApplicationBuilder
        ConfigureSwaggerUi(
            this IApplicationBuilder app,
            IApiVersionDescriptionProvider apiVersionProvider)
    {
        return app.UseSwaggerUI(
            options =>
            {
                options.DocExpansion(
                    Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.List);

                // Present API version in descending order
                var versionDescriptions = apiVersionProvider
                    .ApiVersionDescriptions
                    .OrderByDescending(desc => desc.ApiVersion)
                    .ToList();

                foreach (var description in versionDescriptions)
                {
                    options.SwaggerEndpoint(
                        $"/swagger/{description.GroupName}/swagger.json",
                        description.GroupName.ToUpperInvariant());
                }
            }
        );
    }
}