如何在 Swagger 端点中设置 Beta 版本控制？

Question

在我的 WebApi 项目（c# 和 .net8）中，我成功设置了以下定义：

对于 1.0 版本，我有这些端点：

但是对于测试版，我想要类似的东西：/beta/api/Auth/Logon。 几乎与 Microsoft 的 Graph Explorer 端点相似：

目前我使用的是2.0版本来区分api版本。 知道如何做到这一点吗？这就是我在代码中的内容：

namespace My.API.Controllers
{
   [ApiVersion("2.0")]
   [Route("v{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>
       /// Gets list of available environments.
       /// </summary>
       /// <returns></returns>
       [AllowAnonymous]
       [HttpGet]
       [Route("/v{version:apiVersion}/api/[controller]/Environments")]
       [ApiExplorerSettings(GroupName = "beta")]
       [ProducesResponseType(type: typeof(List<GWEnvironments>), statusCode: 200)]
       [ProducesResponseType(type: typeof(string), statusCode: 400)]
       [Produces("application/json", "application/xml")]
       public ActionResult<List<GWEnvironments>> Environments()
       {
       }
  }

}

提前致谢。

Answer 1

ApiVersion 有规定的格式，无法更改。这对于整理、排序和比较很重要。例如，

1.0

、

1.0-beta

。您可以这样定义：

[ApiVersion(1.0,"beta")]

。

其实不需要为你的 beta api 定义 ApiVersion 也可以实现你的要求，只需添加

[Route]

和

[ApiExplorerSettings]

属性，如下所示：

[Route("beta/api/[controller]")]
[ApiController]
[ApiExplorerSettings(GroupName = "beta")]
public class BetaAdminController : ControllerBase
{
    [HttpGet]
    [Route("Logon")]
    public IActionResult BetaLogon()
    {
        // Beta API method
        return Ok("Beta Logon successful");
    }
}

确保 Program.cs 配置如下：

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.OpenApi.Models;
using Asp.Versioning;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    // Generate Swagger documentation for both versions
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API v1", Version = "v1" });
    options.SwaggerDoc("beta", new OpenApiInfo { Title = "My Beta API", Version = "beta" });
});
builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
}).AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

builder.Services.AddProblemDetails();
var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    //app.UseSwaggerUI();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
        c.SwaggerEndpoint("/swagger/beta/swagger.json", "Beta");
    });
}

app.UseHttpsRedirection();
app.UseExceptionHandler();

app.UseAuthorization();

app.MapControllers();

app.Run();

另外请务必添加包：

<PackageReference Include="Asp.Versioning.Http" Version="8.1.0" />
<PackageReference Include="Asp.Versioning.Mvc.ApiExplorer" Version="8.1.0" />