-
Notifications
You must be signed in to change notification settings - Fork 1.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Observe the route template constraints in the Swagger middleware
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:
```csharp
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](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/routing?view=aspnetcore-6.0#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.- Loading branch information
Showing
11 changed files
with
166 additions
and
12 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
25 changes: 25 additions & 0 deletions
25
test/Swashbuckle.AspNetCore.IntegrationTests/SwaggerAndSwaggerUIIntegrationTests.cs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| using System.Net; | ||
| using System.Threading.Tasks; | ||
| using Microsoft.AspNetCore.Mvc.Testing; | ||
| using Xunit; | ||
|
|
||
| namespace Swashbuckle.AspNetCore.IntegrationTests | ||
| { | ||
| public class SwaggerAndSwaggerUIIntegrationTests | ||
| { | ||
| [Theory] | ||
| [InlineData("/swagger/index.html", "text/html")] | ||
| [InlineData("/swagger/v1.json", "application/json")] | ||
| [InlineData("/swagger/v1.yaml", "text/yaml")] | ||
| [InlineData("/swagger/v1.yml", "text/yaml")] | ||
| public async Task SwaggerDocWithoutSubdirectory(string path, string mediaType) | ||
| { | ||
| var client = new WebApplicationFactory<TopLevelSwaggerDoc.Program>().CreateClient(); | ||
|
|
||
| var response = await client.GetAsync(path); | ||
|
|
||
| Assert.Equal(HttpStatusCode.OK, response.StatusCode); | ||
| Assert.Equal(mediaType, response.Content.Headers.ContentType?.MediaType); | ||
| } | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| using Microsoft.OpenApi.Models; | ||
|
|
||
| namespace TopLevelSwaggerDoc; | ||
|
|
||
| public class Program | ||
| { | ||
| public static void Main(string[] args) | ||
| { | ||
| 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 = c.RouteTemplate.Replace("swagger/{documentName}/swagger.", "swagger/{documentName}.")); | ||
| app.UseSwaggerUI(c => c.SwaggerEndpoint("v1.json", "Test API")); | ||
|
|
||
| app.Run(); | ||
| } | ||
| } |
28 changes: 28 additions & 0 deletions
28
test/WebSites/TopLevelSwaggerDoc/Properties/launchSettings.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| { | ||
| "iisSettings": { | ||
| "windowsAuthentication": false, | ||
| "anonymousAuthentication": true, | ||
| "iisExpress": { | ||
| "applicationUrl": "http://localhost:12841", | ||
| "sslPort": 44316 | ||
| } | ||
| }, | ||
| "profiles": { | ||
| "TopLevelSwaggerDoc": { | ||
| "commandName": "Project", | ||
| "dotnetRunMessages": true, | ||
| "launchBrowser": true, | ||
| "applicationUrl": "https://localhost:7028;http://localhost:5225", | ||
| "environmentVariables": { | ||
| "ASPNETCORE_ENVIRONMENT": "Development" | ||
| } | ||
| }, | ||
| "IIS Express": { | ||
| "commandName": "IISExpress", | ||
| "launchBrowser": true, | ||
| "environmentVariables": { | ||
| "ASPNETCORE_ENVIRONMENT": "Development" | ||
| } | ||
| } | ||
| } | ||
| } |
15 changes: 15 additions & 0 deletions
15
test/WebSites/TopLevelSwaggerDoc/TopLevelSwaggerDoc.csproj
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| <Project Sdk="Microsoft.NET.Sdk.Web"> | ||
|
|
||
| <PropertyGroup> | ||
| <TargetFramework>net6.0</TargetFramework> | ||
| <Nullable>enable</Nullable> | ||
| <ImplicitUsings>enable</ImplicitUsings> | ||
| </PropertyGroup> | ||
|
|
||
| <ItemGroup> | ||
| <ProjectReference Include="..\..\..\src\Swashbuckle.AspNetCore.Swagger\Swashbuckle.AspNetCore.Swagger.csproj" /> | ||
| <ProjectReference Include="..\..\..\src\Swashbuckle.AspNetCore.SwaggerGen\Swashbuckle.AspNetCore.SwaggerGen.csproj" /> | ||
| <ProjectReference Include="..\..\..\src\Swashbuckle.AspNetCore.SwaggerUI\Swashbuckle.AspNetCore.SwaggerUI.csproj" /> | ||
| </ItemGroup> | ||
|
|
||
| </Project> |
8 changes: 8 additions & 0 deletions
8
test/WebSites/TopLevelSwaggerDoc/appsettings.Development.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| { | ||
| "Logging": { | ||
| "LogLevel": { | ||
| "Default": "Information", | ||
| "Microsoft.AspNetCore": "Warning" | ||
| } | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| { | ||
| "Logging": { | ||
| "LogLevel": { | ||
| "Default": "Information", | ||
| "Microsoft.AspNetCore": "Warning" | ||
| } | ||
| }, | ||
| "AllowedHosts": "*" | ||
| } |