Để triển khai kiểm soát phiên bản API kết hợp với tài liệu Swagger trong ứng dụng ASP.NET Core, cần sử dụng các thư viện sau:

• Microsoft.AspNetCore.Mvc.Versioning
• Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

Đăng ký dịch vụ phiên bản API

builder.Services.AddApiVersioning(options =>
{
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true;
});

builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

Ví dụ controller hỗ trợ nhiều phiên bản

[ApiVersion("1.0")]
[ApiVersion("2.0")]
[Route("api/[controller]")]
[ApiController]
public class ProductsController : ControllerBase
{
    [HttpPost]
    public IActionResult CreateV1()
    {
        return Ok(new { Version = "1.0", Action = "Create" });
    }

    [HttpPost]
    [MapToApiVersion("2.0")]
    public IActionResult CreateV2()
    {
        return Ok(new { Version = "2.0", Action = "Create" });
    }
}

Controller chỉ hỗ trợ phiên bản 1.0

[ApiVersion("1.0")]
[Route("api/[controller]")]
[ApiController]
public class OrdersController : ControllerBase
{
    [HttpGet]
    public IActionResult GetAll()
    {
        return Ok(new { Version = "1.0", Resource = "Orders" });
    }
}

Cấu hình SwaggerGenOptions để tạo tài liệu theo từng phiên bản

public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions>
{
    private readonly IApiVersionDescriptionProvider _provider;

    public ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider)
    {
        _provider = provider;
    }

    public void Configure(SwaggerGenOptions options)
    {
        foreach (var description in _provider.ApiVersionDescriptions)
        {
            options.SwaggerDoc(
                description.GroupName,
                new OpenApiInfo
                {
                    Title = $"My API {description.ApiVersion}",
                    Version = description.ApiVersion.ToString(),
                    Description = $"API version {description.ApiVersion}"
                });
        }
    }
}

Đăng ký lớp cấu hình này trong DI container:

builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();
builder.Services.AddSwaggerGen();

Thiết lập middleware Swagger và Swagger UI

var app = builder.Build();

app.UseSwagger();

var descriptionsProvider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();

app.UseSwaggerUI(options =>
{
    options.RoutePrefix = string.Empty;
    options.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.List);
    options.EnableFilter();

    foreach (var description in descriptionsProvider.ApiVersionDescriptions)
    {
        options.SwaggerEndpoint(
            $"/swagger/{description.GroupName}/swagger.json",
            $"API {description.GroupName}"
        );
    }
});

Sử dụng ReDoc thay cho Swagger UI

Cài đặt gói Swashbuckle.AspNetCore.ReDoc, sau đó cấu hình như sau:

app.UseReDoc(options =>
{
    options.DocumentTitle = "API Documentation";
    options.RoutePrefix = "redoc";

    // Chỉ hiển thị phiên bản mới nhất hoặc chọn một phiên bản cụ thể
    var latestDescription = descriptionsProvider.ApiVersionDescriptions
        .OrderByDescending(d => d.ApiVersion)
        .First();

    options.SpecUrl = $"/swagger/{latestDescription.GroupName}/swagger.json";
});

Truy cập tài liệu ReDoc tại: /redoc