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`) diff --git a/docs/OpenApi/ProblemResponses.md b/docs/OpenApi/ProblemResponses.md index 46473b3..5a4fd2e 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 `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 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/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. diff --git a/tests/Core.OpenApi.Swashbuckle.IntegrationTests/OpenApiRegistrationCoverageTests.cs b/tests/Core.OpenApi.Swashbuckle.IntegrationTests/OpenApiRegistrationCoverageTests.cs index 5b9f084..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] @@ -40,6 +41,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() { 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]