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

问题描述

我正在尝试使用使用查询字符串和标头的API版本控制来实现dotnet网络api。在这里，我使用摇摇欲坠来记录和测试端点。我成功地使用了路径版本控制，并以夸张的方式反映了端点。但是我很难理解如何在大范围内反映查询字符串和标头版本。我试图从本文below are the necessary app permission中找到一个解决方案，但仍然对如何在我的dotnet网络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");
        });
        }
        }
        }

解决方法

@ michael-wang是正确的。您还需要包括API Versioning API Explorer扩展名。此扩展使API发现API版本意识到。此信息的许多可能用途之一是OpenAPI / Swagger集成。

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