Observe the route template constraints in the Swagger middleware

[0xced]

The default route template, i.e. swagger/{documentName}/swagger.{json|yaml} which is used by the SwaggerMiddleware is problematic because it matches any file extension. Even though it looks like only json and yaml extensions are supported, actually any extension matches. Trying to hit the following endpoints all return the JSON swagger document:

• swagger/v1/swagger.xml
• swagger/v1/swagger.yml
• swagger/v1/swagger.anything

This is not a very big deal, until the SwaggerUIMiddleware is also used and one chooses to modify the default route to swagger/{documentName}.{json|yaml}.

This is the problematic configuration:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddMvcCore().AddApiExplorer();
builder.Services.AddSwaggerGen(c => c.SwaggerDoc("v1", new OpenApiInfo { Title = "Test API", Version = "1" }));
var app = builder.Build();

app.UseSwagger(c => c.RouteTemplate = "swagger/{documentName}.{json|yaml}");
app.UseSwaggerUI(c => c.SwaggerEndpoint("v1.json", "Test API"));

app.Run();

At this point, the SwaggerMiddleware will try to serve swagger/index.html because the route template matches (documentName = index and json|yaml = html) but the index document doesn't exist and this results in a 404 instead of calling the next (SwaggerUI) middleware.

To fix this issue, the default route template has been modified to swagger/{documentName}/swagger.{extension:regex(^(json|ya?ml)$)}, leveraging ASP.NET Core route constraints and the constraints are actually enforced in the SwaggerMiddleware implementation.

The default route template has also been modified in the MapSwagger method to ensure that only json, yaml and yml extensions are supported by default.

[martincostello]

Thanks for contributing - if you'd like to continue with this pull request, please rebase against the default branch to pick up our new CI. Are any more specific asserts needed in the integration test you've added?

[0xced]

Great to see that Swashbuckle.AspNetCore is not dead! I rebased my branch onto master, ready for the GitHub workflows to run.

I don't think more asserts are warranted as the new integration test fully covers the problem described. (It would not pass without the changes in the route constraint handling.)

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 91.99%. Comparing base (9e77996) to head (8de9a70).
Report is 5 commits behind head on master.

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2418      +/-   ##
==========================================
+ Coverage   91.66%   91.99%   +0.33%     
==========================================
  Files          91       91              
  Lines        3010     3036      +26     
  Branches      517      522       +5     
==========================================
+ Hits         2759     2793      +34     
+ Misses        251      243       -8     

Flag	Coverage Δ
Linux	91.99% <100.00%> (+0.33%)	⬆️
Windows	91.99% <100.00%> (+0.33%)	⬆️
macOS	91.99% <100.00%> (+0.33%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.