From d91968b53327ce2868292a9be2123b36d7e6c503 Mon Sep 17 00:00:00 2001 From: Dave Callan <106764096+davepcallan@users.noreply.github.com> Date: Thu, 23 Jan 2025 11:22:34 +0000 Subject: [PATCH 1/4] Move MapOpenApi() Inside the IsDevelopment() block for consistency with templates and other docs The default template with .NET 9 has MapOpenApi() inside the IsDevelopment block. Many examples on MS Learn also have it inside due to limit information exposure. Move inside to minimize potential for confusion to devs. --- .../fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs b/aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs index 3de9cb2e1f80..bf6328e22ae3 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs +++ b/aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs @@ -279,9 +279,10 @@ public class Body { var app = builder.Build(); -app.MapOpenApi(); if (app.Environment.IsDevelopment()) { + app.MapOpenApi(); + app.UseSwaggerUI(options => { options.SwaggerEndpoint("/openapi/v1.json", "v1"); From 70123d086b6640ef44e45cbf3377e6ad11a6eea1 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Thu, 23 Jan 2025 10:00:27 -0800 Subject: [PATCH 2/4] Conditionally map all calls to OpenApi in development environment --- .../samples/9.x/WebMinOpenApi/Program.cs | 53 ++++++++++++++----- 1 file changed, 41 insertions(+), 12 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs b/aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs index bf6328e22ae3..5dd7523b220d 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs +++ b/aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs @@ -3,7 +3,6 @@ //#define DOCUMENTtransformer1 //#define DOCUMENTtransformer2 #define DOCUMENTtransformerUse999 -//#define DEFAULT //#define FIRST //#define OPENAPIWITHSCALAR //#define MAPOPENAPIWITHCACHING @@ -80,7 +79,10 @@ internal record WeatherForecast(DateTime Date, int TemperatureC, string? Summary var app = builder.Build(); -app.MapOpenApi(); +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} app.MapGet("/", () => "Hello world!"); @@ -107,7 +109,10 @@ internal record WeatherForecast(DateTime Date, int TemperatureC, string? Summary var app = builder.Build(); -app.MapOpenApi(); +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} app.MapGet("/", () => "Hello world!"); @@ -161,7 +166,10 @@ public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransf var app = builder.Build(); -app.MapOpenApi(); +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} app.MapGet("/", () => "Hello world!"); @@ -189,7 +197,10 @@ public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransf var app = builder.Build(); -app.MapOpenApi(); +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} app.MapGet("/world", () => "Hello world!") .WithGroupName("internal"); @@ -253,7 +264,10 @@ public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransf var app = builder.Build(); -app.MapOpenApi(); +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} app.MapGet("/", () => new Body { Amount = 1.1m }); @@ -343,8 +357,11 @@ public class Body { app.UseOutputCache(); -app.MapOpenApi() - .CacheOutput(); +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi() + .CacheOutput(); +} app.MapGet("/", () => "Hello world!"); @@ -366,7 +383,10 @@ public class Body { var app = builder.Build(); -app.MapOpenApi(); +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} if (app.Environment.IsDevelopment()) { @@ -387,7 +407,10 @@ public class Body { var app = builder.Build(); -app.MapOpenApi(); +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} app.MapGet("/", () => "Hello world!"); @@ -420,7 +443,10 @@ public class Body { var app = builder.Build(); -app.MapOpenApi(); +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} app.MapGet("/", () => "Hello world!"); @@ -474,7 +500,10 @@ public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext var app = builder.Build(); -app.MapOpenApi(); +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} app.MapGet("/", () => "Hello world!"); From 1664eaad96694c2e288b2ad5ff2e77d25c637d27 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Thu, 23 Jan 2025 10:25:17 -0800 Subject: [PATCH 3/4] Combined MapOpenAPI and MapScalar in same env condition Line 501, moved app.MapOpenAPI() to same environment condition block for app.MapScalarApiReference() --- .../fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs | 4 ---- 1 file changed, 4 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs b/aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs index 5dd7523b220d..cd215fece33c 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs +++ b/aspnetcore/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs @@ -386,10 +386,6 @@ public class Body { if (app.Environment.IsDevelopment()) { app.MapOpenApi(); -} - -if (app.Environment.IsDevelopment()) -{ app.MapScalarApiReference(); } From aabdd2a46ed4b42596b12b7ec4ab88aff074a35c Mon Sep 17 00:00:00 2001 From: wadepickett Date: Thu, 23 Jan 2025 11:00:36 -0800 Subject: [PATCH 4/4] Updated code highlight --- aspnetcore/fundamentals/openapi/aspnetcore-openapi.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md index 69a1295fc2d2..23626b6a9318 100644 --- a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md +++ b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md @@ -5,7 +5,7 @@ description: Learn how to generate and customize OpenAPI documents in an ASP.NET ms.author: safia monikerRange: '>= aspnetcore-6.0' ms.custom: mvc -ms.date: 12/11/2024 +ms.date: 01/23/2025 uid: fundamentals/openapi/aspnetcore-openapi --- # Generate OpenAPI documents @@ -48,7 +48,7 @@ The following code: * Adds OpenAPI services using the extension method on the app builder's service collection. * Maps an endpoint for viewing the OpenAPI document in JSON format with the extension method on the app. -[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_first&highlight=3,7)] +[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_first&highlight=3,9)] Launch the app and navigate to `https://localhost:/openapi/v1.json` to view the generated OpenAPI document.