asp.net-core - SwagggerUI でクエリ文字列パラメーターを使用する dotnet Web API エンドポイントを反映するにはどうすればよいですか?

Question

クエリ文字列とヘッダーを使用する API バージョン管理で dotnet Web API を実装しようとしています。ここでは、swagger を使用してエンドポイントを文書化し、テストしています。パスのバージョン管理をうまく使用し、エンドポイントを Swagger に反映しました。しかし、クエリ文字列とヘッダーのバージョン管理をswaggerに反映する方法を理解するのに苦労しています。この記事https://swagger.io/docs/specification/describing-parameters/#query-parametersから解決策を見つけようとしましたが、ドットネット Web API でこれを実装する方法がまだ混乱していました。

私のプロジェクトには、次の API バージョンを持つ 2 つの主要なコントローラー クラスが含まれています。

1. WeatherForecastController.cs

    namespace QueryStringVersioning.Controllers
    {
    [ApiController]
    [ApiVersion("1.0")]
    [ApiVersion("1.1", Deprecated = true)]
    [ApiVersion("3.0")]
    [Route ("api")] //support query string & header versioning
    // [Route("api/v{version:apiVersion}/[controller]")] //support path versioning 
    public class WeatherForecastController : ControllerBase
    {
    private static readonly string[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", 
    "Scorching"
    };
   
    private readonly ILogger<WeatherForecastController> _logger;
   
    public WeatherForecastController(ILogger<WeatherForecastController> logger)
    {
        _logger = logger;
    }
   
    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        var rng = new Random();
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateTime.Now.AddDays(index),
            TemperatureC = rng.Next(-20, 55),
            Summary = Summaries[rng.Next(Summaries.Length)]
        })
        .ToArray();
    }
   
   
    [HttpGet, MapToApiVersion("3.0")]
    public IActionResult GetV3_0() => Ok(new string[] { "MapToApiVersion value 3.0" });
   
    [HttpGet, MapToApiVersion("1.1")]
    public IActionResult GetV1_1() => Ok(new string[] { "Depreceated MapToApiVersion value" });
    }}
   

2. WeatherForecastController2.cs

    namespace QueryStringVersioning.Controllers2
    {
    [ApiController]
    [ApiVersion("2.0")]
    [ApiVersion("2.1")]
    [Route ("api")] //support query string & header versioning
    // [Route("api/v{version:apiVersion}/[controller]")] //support path versioning 
    public class WeatherForecastController : ControllerBase
    {
    public IActionResult GetV2_0() => Ok(new string[] { "This is API Version 2.0" });
   
    [HttpGet, MapToApiVersion("2.1")]
    public IActionResult GetV2_1() => Ok(new string[] { "This is API Version 2.1" });
    }}
   

そして、startup.cs ファイル

    namespace QueryStringVersioning
    {
    public class Startup
    {
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddSwaggerGen(c =>
        {

            c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
            {
                Version = "v1",
                Title = "API_Versioning V1",
            });

            c.SwaggerDoc("v1.1", new Microsoft.OpenApi.Models.OpenApiInfo
            {
                Version = "v1.1",
                Title = "API_Versioning V1.1",
                
            });

            c.SwaggerDoc("v2", new Microsoft.OpenApi.Models.OpenApiInfo
            {
                Version = "v2",
                Title = "API_Versioning V2"
            });

            c.SwaggerDoc("v2.1", new Microsoft.OpenApi.Models.OpenApiInfo
            {
                Version = "v2.1",
                Title = "API_Versioning V2.1"
            });

            c.SwaggerDoc("v3", new Microsoft.OpenApi.Models.OpenApiInfo
            {
                Version = "v3",
                Title = "API_Versioning V3"
            });
            
            c.ResolveConflictingActions (apiDescriptions => apiDescriptions.First ());
            // c.OperationFilter<RemoveVersionFromParameter>();
            // c.DocumentFilter<ReplaceVersionWithExactValueInPath>();
             
            
                    
        });
        services.AddControllers();
        services.AddMvc();
        services.AddApiVersioning(option =>
        {
            option.ReportApiVersions = true;
            option.AssumeDefaultVersionWhenUnspecified = true;
            option.DefaultApiVersion = new ApiVersion(1, 0);
            // Supporting multiple versioning scheme
            option.ApiVersionReader = ApiVersionReader.Combine(new HeaderApiVersionReader("X-version"), new QueryStringApiVersionReader("api-version"));
            
        });

    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseHttpsRedirection();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });

        // Enable middleware to serve generated Swagger as a JSON endpoint.
        app.UseSwagger();
        // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
        // specifying the Swagger JSON endpoint.
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "API_Versioning V1.0");
            c.SwaggerEndpoint("/swagger/v1.1/swagger.json", "API_Versioning V1.1");
            c.SwaggerEndpoint("/swagger/v2/swagger.json", "API_Versioning V2.0");
            c.SwaggerEndpoint("/swagger/v2.1/swagger.json", "API_Versioning V2.1");
            c.SwaggerEndpoint("/swagger/v3/swagger.json", "API_Versioning V3.0");
        });
        }
        }
        }