如何在 SwaggerUI 中反映使用查询字符串参数的 dotnet Web api 端点？

Question

我正在尝试通过使用查询字符串和标头的 API 版本控制来实现 dotnet Web api。在这里，我使用 swagger 来记录和测试端点。我成功地使用了路径版本控制并以大摇大摆的方式反映了端点。但是我很难理解如何在招摇中反映查询字符串和标头版本控制。我试图从这篇文章https://swagger.io/docs/specification/describing-parameters/#query-parameters 中找到解决方案，但仍然对如何在我的 dotnet web api 中实现这一点感到困惑。

我的项目包含 2 个具有以下 API 版本的主要控制器类。

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

Answer 1

@michael-wang 是正确的。您还需要包含API Versioning API Explorer 扩展。此扩展使 API 发现 API 版本感知。此信息的众多可能用途之一是 OpenAPI/Swagger 集成。

API Versioning 登录页面上列出了所有适用的 NuGet 包的链接。还有一个使用 Swashbuckle 提供的end-to-end example。