Блог

Я пытаюсь реализовать dotnet web api с управлением версиями API, который использует строки и заголовки запросов. Здесь я использую swagger для документирования и тестирования конечных точек. Я успешно использовал управление версиями пути и отразил конечные точки в swagger. Но я изо всех сил пытаюсь понять, как отразить управление версиями строки запроса и заголовка в 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 amp; 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 amp; 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 для управления версиями API Explorer. Эти расширения делают версию API обнаружения API осведомленной. Одним из многих возможных применений этой информации является интеграция OpenAPI / Swagger.

Ссылки на все применимые пакеты NuGet перечислены на целевой странице управления версиями API. Существует также сквозной пример, представленный с использованием Swashbuckle.