Swagger UI 中的 API 版本控制

Question

我正在研究 .net 核心 6、API 版本控制，并试图在 swagger UI 中显示两个版本“v1”和“v2”，但仅显示“v1”。

这是我的program.cs代码

   builder.Services.AddApiVersioning(setup =>
    {
        setup.DefaultApiVersion = new ApiVersion(1,0);
        setup.AssumeDefaultVersionWhenUnspecified = true;
        setup.ReportApiVersions = true;
    });

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

    builder.Services.AddSwaggerGen(options =>
    {
        
        options.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v1",
            Title = "API",
            Description = "An API in dotnet core 6",

        });
        var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        options.IncludeXmlComments(Path.Combine($@"{AppContext.BaseDirectory}", xmlFilename));
    });

    if (app.Environment.IsDevelopment())
    {
        app.UseSwagger();
        app.UseSwaggerUI();
    }

v1 controller 有这个动作方法

    [MapToApiVersion("1.0")]
    [HttpGet]
    [Route("GetLast12MonthBalances")]
    public async Task<ApiResponse> GetLast12MonthBalances()
    {

v2 controller 有这个动作方法

   [MapToApiVersion("2.0")]
   [HttpGet,Route("GetLast12MonthBalances")]
   public async Task<ApiResponse> GetLast12MonthBalances()
   {

知道缺少什么吗？

Answer 1

您需要使用选项模式配置 SwaggerGenOptions。

1st- 创建一个 class 如下：

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

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

        public void Configure(SwaggerGenOptions options)
        {
            // add swagger document for every API version discovered
            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 = "My API",
                Version = description.ApiVersion.ToString()
            };

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

            return info;
        }
    }
}

将选项与服务集合连接起来

public void ConfigureServices(IServiceCollection services)
{
    services.AddScoped<ITestsRepository, TestssRepository>();
    services.AddControllers();

    services.AddApiVersioning(setup =>
    {
        setup.DefaultApiVersion = new ApiVersion(1, 0);
        setup.AssumeDefaultVersionWhenUnspecified = true;
        setup.ReportApiVersions = true;
    });

    services.AddVersionedApiExplorer(setup =>
    {
        setup.GroupNameFormat = "'v'VVV";
        setup.SubstituteApiVersionInUrl = true;
    });

    services.AddSwaggerGen();
    services.ConfigureOptions<ConfigureSwaggerOptions>();
}