如何在Swagger端点中配置Beta版本控制（.NET 8 WebAPI）

1. 配置API版本支持（Program.cs） #

首先在服务配置中启用字符串形式的版本（如"beta"），并配置版本读取规则：

builder.Services.AddApiVersioning(options =>
{
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true;
    // 从URL路径读取版本，支持数字和字符串版本
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
    // 为目标控制器配置支持的版本：2.0和beta
    options.Conventions.Controller<AdminController>()
                      .HasApiVersion(new ApiVersion(2, 0))
                      .HasApiVersion("beta");
});

// 配置Swagger多版本显示（若使用Swagger）
builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
    options.SubstitutionFormat = "beta";
});

2. 修改控制器路由与版本属性 #

方式一：单控制器兼容双版本路径 #

调整控制器属性，让同一个控制器同时响应正式版（v2.0）和Beta版路径：

namespace My.API.Controllers
{
    [ApiVersion("2.0")]
    [ApiVersion("beta")]
    // 路由模板兼容数字版本和beta字符串
    [Route("{version:apiVersion}/api/[controller]")]
    [ApiController]
    public class AdminController : ControllerBaseExtra
    {
        private readonly ILoggerManager _logger;
        private readonly IConfiguration _configuration;
        private readonly ISessionUtility _sessionUtility;
        private HttpClient _client;

        public AdminController(ISessionUtility sessionUtility, IConfiguration configuration, ILoggerManager logger)
        {
            _configuration = configuration;
            _logger = logger;
            _sessionUtility = sessionUtility;
            _client = new HttpClient(new LoggingHandler(logger, new HttpClientHandler()));
        }

        /// <summary>
        /// 获取可用环境列表
        /// </summary>
        [AllowAnonymous]
        [HttpGet("Environments")]
        // 指定该方法映射到两个版本
        [MapToApiVersion("2.0")]
        [MapToApiVersion("beta")]
        [ApiExplorerSettings(GroupName = "beta")]
        [ProducesResponseType(typeof(List<GWEnvironments>), 200)]
        [ProducesResponseType(typeof(string), 400)]
        [Produces("application/json", "application/xml")]
        public ActionResult<List<GWEnvironments>> Environments()
        {
            // 业务逻辑实现
        }
    }
}

配置完成后，该接口会同时响应两个路径：

• GET /v2.0/api/Admin/Environments（正式版）
• GET /beta/api/Admin/Environments（Beta版）

方式二：独立Beta控制器（更清晰） #

若希望Beta版本与正式版完全分离，可单独创建Beta控制器：

namespace My.API.Controllers
{
    [ApiVersion("beta")]
    // 直接指定Beta版路由格式
    [Route("beta/api/Admin")]
    [ApiController]
    public class BetaAdminController : ControllerBaseExtra
    {
        private readonly ILoggerManager _logger;
        private readonly IConfiguration _configuration;
        private readonly ISessionUtility _sessionUtility;
        private HttpClient _client;

        public BetaAdminController(ISessionUtility sessionUtility, IConfiguration configuration, ILoggerManager logger)
        {
            _configuration = configuration;
            _logger = logger;
            _sessionUtility = sessionUtility;
            _client = new HttpClient(new LoggingHandler(logger, new HttpClientHandler()));
        }

        [AllowAnonymous]
        [HttpGet("Environments")]
        [ApiExplorerSettings(GroupName = "beta")]
        [ProducesResponseType(typeof(List<GWEnvironments>), 200)]
        [ProducesResponseType(typeof(string), 400)]
        [Produces("application/json", "application/xml")]
        public ActionResult<List<GWEnvironments>> Environments()
        {
            // Beta版专属业务逻辑
        }
    }
}

此方式下Beta版接口路径为GET /beta/api/Admin/Environments，完全匹配Microsoft Graph的格式。

3. 注意事项 #

• 确保使用最新版的Microsoft.AspNetCore.Mvc.Versioning包（.NET 8对应5.x及以上版本）。
• 若使用Swagger，需配置多版本文档，让Beta版接口单独分组显示。
• 检查路由规则，避免正式版与Beta版路径冲突。

内容的提问来源于stack exchange，提问作者Inoel