Description
In upgrading applications from DotNet 6.0 to DotNet 8.0 I encountered an issue with routing version neutrality.
My existing implementation has a neutral healthcheck controller that accomplishes the following:
- HealthCheck endpoints resolve in swagger for each present version
- HealthCheck endpoint is responsive at any agnostic version, or versions not explicitly in use by the application (example/api/v999/healthcheck)
Here is my current structure:
using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;
namespace example.Controller
{
[ApiVersionNeutral]
[ApiController]
[Route("example/api/[controller]/[action]")]
public class HealthCheckController : ControllerBase
{
[HttpGet]
public IActionResult Heartbeat() => Ok("Beep");
}
}
In Swagger this appears as:
However, after the upgrade I can no longer target the healthcheck endpoint agnostically. For any version beyond what's in specific use by my application controllers I will receive a 404 not found.
This is an issue for service infrastructure that targets a v1/healthcheck on an application that no longer has v1 controllers.
I was able to overcome this behavior by modifying my route to {version:int}:
[ApiVersionNeutral]
[ApiController]
[Route("example/api/v{version:int}/[controller]/[action]")]
public class HealthCheckController : ControllerBase
{
[HttpGet]
public IActionResult Heartbeat() => Ok("Beep");
}
but this is undesirable as it breaks my swagger UI - expecting a parameter:
For reference here is how my application versioning is configured:
public static void ConfigureApiVersioning(this IServiceCollection services)
{
services.AddApiVersioning(
options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.ReportApiVersions = true;
options.AssumeDefaultVersionWhenUnspecified = true;
options.ApiVersionReader = new UrlSegmentApiVersionReader();
})
.AddApiExplorer(
options =>
{
options.GroupNameFormat = "'v'VVV";
options.SubstituteApiVersionInUrl = true;
options.AddApiVersionParametersWhenVersionNeutral = true;
});
}
Where there any breaking changes around the ApiVersionNeutral attribute?