我正在尝试使用使用查询字符串和标头的 API 版本控制来实现 dotnet web api。在这里,我使用 swagger 来记录和测试端点。我成功地使用了路径版本控制并以大摇大摆的方式反映了端点。但是我很难理解如何在招摇中反映查询字符串和标头版本控制。我试图从这篇文章https://swagger.io/docs/specification/describing-parameters/#query-parameters中找到解决方案,但仍然对如何在我的 dotnet web api 中实现这一点感到困惑。
我的项目包含 2 个具有以下 API 版本的主要控制器类。
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" }); }}
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");
});
}
}
}