From 5f0696057ac7a1ca57e4e4573bbf14339c33257b Mon Sep 17 00:00:00 2001 From: fpgutierrez Date: Sun, 15 Nov 2026 18:16:25 -0500 Subject: [PATCH 1/4] fix(swashbuckle): skip wildcard listen addresses in Development servers In Development, AddCoreOpenApi appends every ASPNETCORE_URLS entry as a "Local" server. Container listen addresses such as http://+:8080 are binding patterns, not URLs a client can call, so they were published in the document. - Skip wildcard hosts (+, *, 0.0.0.0, [::]) when building Local servers. - Document that ProblemResponses.SchemaId defaults to ProblemDetails and must name the error schema in use (for example CoreProblemDetails), otherwise the generated document contains dangling $ref entries. --- docs/OpenApi/ProblemResponses.md | 6 ++++ .../OpenApiRegistration.cs | 32 +++++++++++++++---- .../OpenApiRegistrationCoverageTests.cs | 29 +++++++++++++++++ 3 files changed, 61 insertions(+), 6 deletions(-) diff --git a/docs/OpenApi/ProblemResponses.md b/docs/OpenApi/ProblemResponses.md index 46473b3..e2c9c7c 100644 --- a/docs/OpenApi/ProblemResponses.md +++ b/docs/OpenApi/ProblemResponses.md @@ -18,6 +18,12 @@ builder.Services.AddCoreOpenApi(options => }); ``` +`SchemaId` names the component that every problem response references. Its default +is `ProblemDetails`, so the document only resolves when your API has a schema with that +exact name. If your error type is `CoreProblemDetails` (the type shipped by this +library), set `SchemaId = "CoreProblemDetails"`; otherwise the generated document +contains a dangling `$ref`. + `IncludeWhenMissing` defaults to `false`, so a status code is only added to operations that already declare it. An existing `400` is replaced only when it already looks like a problem response. \ No newline at end of file diff --git a/src/Core.OpenApi.Swashbuckle/DependencyInjection/OpenApiRegistration.cs b/src/Core.OpenApi.Swashbuckle/DependencyInjection/OpenApiRegistration.cs index 0bfc689..be63e19 100644 --- a/src/Core.OpenApi.Swashbuckle/DependencyInjection/OpenApiRegistration.cs +++ b/src/Core.OpenApi.Swashbuckle/DependencyInjection/OpenApiRegistration.cs @@ -65,14 +65,16 @@ public static IServiceCollection AddCoreOpenApi( var existing = new HashSet(options.Servers.Select(s => s.Url), StringComparer.OrdinalIgnoreCase); foreach (var url in urls.Split(';', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)) { - if (existing.Add(url)) + if (IsWildcardListenAddress(url) || !existing.Add(url)) { - options.Servers.Add(new OpenApiServerDescriptor - { - Url = url, - Description = "Local" - }); + continue; } + + options.Servers.Add(new OpenApiServerDescriptor + { + Url = url, + Description = "Local" + }); } } } @@ -88,6 +90,24 @@ public static IServiceCollection AddCoreOpenApi( return services; } + /// + /// Determines whether a listen address uses a wildcard host, such as http://+:8080, + /// which is a binding pattern rather than an address a client can call. + /// + /// The listen address. + /// when the host is a wildcard; otherwise, . + private static bool IsWildcardListenAddress(string url) + { + var schemeEnd = url.IndexOf("://", StringComparison.Ordinal); + var authority = schemeEnd < 0 ? url : url[(schemeEnd + 3)..]; + var host = authority.Split('/', 2)[0]; + host = host.StartsWith('[') + ? host[..(host.IndexOf(']') + 1)] + : host.Split(':')[0]; + + return host is "+" or "*" or "0.0.0.0" or "[::]"; + } + /// /// Configures the Swagger generator with the CoreSystem conventions. /// diff --git a/tests/Core.OpenApi.Swashbuckle.IntegrationTests/OpenApiRegistrationCoverageTests.cs b/tests/Core.OpenApi.Swashbuckle.IntegrationTests/OpenApiRegistrationCoverageTests.cs index 5b9f084..2a08f56 100644 --- a/tests/Core.OpenApi.Swashbuckle.IntegrationTests/OpenApiRegistrationCoverageTests.cs +++ b/tests/Core.OpenApi.Swashbuckle.IntegrationTests/OpenApiRegistrationCoverageTests.cs @@ -40,6 +40,35 @@ public void AddCoreOpenApi_DevelopmentUrlsAndBearerAndServers() } } + [Fact] + public void AddCoreOpenApi_DevelopmentSkipsWildcardListenAddresses() + { + Environment.SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development"); + Environment.SetEnvironmentVariable("ASPNETCORE_URLS", "http://+:8080;http://*:9000;http://0.0.0.0:80;http://[::]:8081;http://localhost:5000"); + + try + { + var services = new ServiceCollection(); + services.AddLogging(); + services.AddRouting(); + var env = new FakeWebHostEnvironment(); + services.AddSingleton(env); + services.AddSingleton(env); + services.AddCoreOpenApi(); + + var provider = services.BuildServiceProvider(); + var document = provider.GetRequiredService().GetSwagger("v1"); + + Assert.Contains(document.Servers, server => server.Url == "http://localhost:5000"); + Assert.DoesNotContain(document.Servers, server => server.Url.Contains('+') || server.Url.Contains('*') || server.Url.Contains("0.0.0.0") || server.Url.Contains("[::]")); + } + finally + { + Environment.SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", null); + Environment.SetEnvironmentVariable("ASPNETCORE_URLS", null); + } + } + [Fact] public void AddCoreOpenApi_ConfigureCallbackAndXmlComments() { From 54d92e1d88bd652df710ed1a1ab1686f9feb397b Mon Sep 17 00:00:00 2001 From: fpgutierrez Date: Sun, 15 Nov 2026 18:23:14 -0500 Subject: [PATCH 2/4] feat(openapi): default problem schema to CoreProblemDetails The default ProblemResponses.SchemaId pointed to a ProblemDetails component that the library does not generate, leaving every problem response with a dangling $ref. CoreProblemDetails is the problem type shipped by this library, so it is now the default, and it is recognized as a problem schema by default as well. Behavior change: consumers that relied on the previous default must set SchemaId = "ProblemDetails" explicitly. --- docs/OpenApi/ProblemResponses.md | 8 ++++---- .../Options/OpenApiProblemResponsesOptions.cs | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/OpenApi/ProblemResponses.md b/docs/OpenApi/ProblemResponses.md index e2c9c7c..5a4fd2e 100644 --- a/docs/OpenApi/ProblemResponses.md +++ b/docs/OpenApi/ProblemResponses.md @@ -19,10 +19,10 @@ builder.Services.AddCoreOpenApi(options => ``` `SchemaId` names the component that every problem response references. Its default -is `ProblemDetails`, so the document only resolves when your API has a schema with that -exact name. If your error type is `CoreProblemDetails` (the type shipped by this -library), set `SchemaId = "CoreProblemDetails"`; otherwise the generated document -contains a dangling `$ref`. +is `CoreProblemDetails`, the problem type shipped by this library, so the generated +document resolves without extra configuration. Set it only when your API uses a +different error type, and make sure a schema with that exact name exists; otherwise +the document contains a dangling `$ref`. `IncludeWhenMissing` defaults to `false`, so a status code is only added to operations that already declare it. An existing `400` is replaced only when it diff --git a/src/Core.OpenApi/Options/OpenApiProblemResponsesOptions.cs b/src/Core.OpenApi/Options/OpenApiProblemResponsesOptions.cs index aa6f96b..e9a2166 100644 --- a/src/Core.OpenApi/Options/OpenApiProblemResponsesOptions.cs +++ b/src/Core.OpenApi/Options/OpenApiProblemResponsesOptions.cs @@ -29,9 +29,9 @@ public OpenApiProblemResponsesOptions() /// /// /// The schema component name used when a definition does not declare its own. - /// The default value is ProblemDetails. + /// The default value is CoreProblemDetails, the problem type shipped by this library. /// - public string SchemaId { get; set; } = "ProblemDetails"; + public string SchemaId { get; set; } = "CoreProblemDetails"; /// /// Gets or sets the media type used by the responses. @@ -69,10 +69,10 @@ public OpenApiProblemResponsesOptions() /// The schema names used by /// to /// decide whether an existing response already describes a problem. The collection - /// contains ProblemDetails and ValidationProblemDetails by default. + /// contains CoreProblemDetails, ProblemDetails and ValidationProblemDetails by default. /// public IList ProblemSchemaIds { get; } = - new List { "ProblemDetails", "ValidationProblemDetails" }; + new List { "CoreProblemDetails", "ProblemDetails", "ValidationProblemDetails" }; /// /// Gets the response catalog. From 70f7c9cb55f38b92c8cdb4385d49fa2bec96d753 Mon Sep 17 00:00:00 2001 From: fpgutierrez Date: Sun, 15 Nov 2026 18:23:15 -0500 Subject: [PATCH 3/4] test(swashbuckle): serialize tests that set ASPNETCORE_URLS OpenApiRegistrationTests and OpenApiRegistrationCoverageTests both write process-wide environment variables. Running them in parallel made the Development server assertions intermittently fail. Place both classes in the same xUnit collection so they run sequentially. --- .../OpenApiRegistrationCoverageTests.cs | 1 + .../OpenApiRegistrationTests.cs | 1 + 2 files changed, 2 insertions(+) diff --git a/tests/Core.OpenApi.Swashbuckle.IntegrationTests/OpenApiRegistrationCoverageTests.cs b/tests/Core.OpenApi.Swashbuckle.IntegrationTests/OpenApiRegistrationCoverageTests.cs index 2a08f56..812b7e9 100644 --- a/tests/Core.OpenApi.Swashbuckle.IntegrationTests/OpenApiRegistrationCoverageTests.cs +++ b/tests/Core.OpenApi.Swashbuckle.IntegrationTests/OpenApiRegistrationCoverageTests.cs @@ -6,6 +6,7 @@ namespace Core.OpenApi.Swashbuckle.IntegrationTests; +[Collection("ProcessEnvironment")] public class OpenApiRegistrationCoverageTests { [Fact] diff --git a/tests/Core.OpenApi.Swashbuckle.IntegrationTests/OpenApiRegistrationTests.cs b/tests/Core.OpenApi.Swashbuckle.IntegrationTests/OpenApiRegistrationTests.cs index 0836668..b0e9d09 100644 --- a/tests/Core.OpenApi.Swashbuckle.IntegrationTests/OpenApiRegistrationTests.cs +++ b/tests/Core.OpenApi.Swashbuckle.IntegrationTests/OpenApiRegistrationTests.cs @@ -5,6 +5,7 @@ namespace Core.OpenApi.Swashbuckle.IntegrationTests; +[Collection("ProcessEnvironment")] public class OpenApiRegistrationTests { [Fact] From bfe8d18ff1b3a25c7134b067aceec7affdd33845 Mon Sep 17 00:00:00 2001 From: fpgutierrez Date: Sun, 15 Nov 2026 18:55:16 -0500 Subject: [PATCH 4/4] docs(openapi): clarify Docker and mapped-port server configuration --- docs/OpenApi/Configuration.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/OpenApi/Configuration.md b/docs/OpenApi/Configuration.md index 8a57845..496c1ba 100644 --- a/docs/OpenApi/Configuration.md +++ b/docs/OpenApi/Configuration.md @@ -4,6 +4,21 @@ Configure via `CoreOpenApiOptions` (extends `OpenApiOptions`): - `Title`, `Description`, `Version`, `DocumentName` - `Servers` (`IList`) + +> **Docker / port mapping:** In Development the library appends the addresses from +> `ASPNETCORE_URLS`/`DOTNET_URLS` as "Local" servers, but only when the host is a +> concrete (non-wildcard) address. When the app binds to a wildcard address such as +> `http://+:8080` (common in containers), or when the host port differs from the +> container port (for example `-p 80:8080`), the binding cannot be turned into a +> callable URL automatically. In those cases add the server manually, for example: +> +> ```csharp +> options.Servers.Add(new OpenApiServerDescriptor +> { +> Url = "http://localhost:80", +> Description = "Local" +> }); +> ``` - `Bearer` security scheme - `IncludeXmlComments`, `XmlCommentFiles`, `IncludeControllerXmlComments` - `SwaggerRoutePrefix` (default `swagger`)