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>();
}