From 33aa35348130adedcc09221b8429161c6af61b75 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Sun, 4 May 2025 16:53:07 -0700 Subject: [PATCH 1/5] WN:v10:Move OpenAPI inline code to sample --- .../aspnetcore-10/includes/openApi.md | 12 ++++++-- .../Controllers/WeatherForecastController.cs | 26 +++++++++++++++++ .../samples/WebAppOpenAPI10/Program.cs | 29 +++++++++++++++++++ .../WebAppOpenAPI10/TransformerJsonNode.diff | 19 ++++++++++++ .../WebAppOpenAPI10/WeatherForecast.cs | 13 +++++++++ .../WebAppOpenAPI10/WebAppOpenAPI10.csproj | 15 ++++++++++ .../WebAppOpenAPI10/WebAppOpenAPI10.http | 6 ++++ .../appsettings.Development.json | 8 +++++ .../samples/WebAppOpenAPI10/appsettings.json | 9 ++++++ 9 files changed, 135 insertions(+), 2 deletions(-) create mode 100644 aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Controllers/WeatherForecastController.cs create mode 100644 aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs create mode 100644 aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/TransformerJsonNode.diff create mode 100644 aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WeatherForecast.cs create mode 100644 aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj create mode 100644 aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.http create mode 100644 aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/appsettings.Development.json create mode 100644 aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/appsettings.json diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md index 867c0e026738..53a151c44cd9 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md @@ -15,7 +15,9 @@ Some of the changes you will see in the generated OpenAPI document include: and have a `pattern` field limiting the value to digits. This happens when the property in the is set to `AllowReadingFromString`, the default for ASP.NET Core Web apps. To enable C# `int` and `long` to be represented in the OpenAPI document as `type: integer`, set the property to `Strict`. -With this feature, the default OpenAPI version for generated documents is`3.1`. The version can be changed by explicitly setting the [OpenApiVersion](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions.openapiversion) property of the [OpenApiOptions](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions) in the `configureOptions` delegate parameter of [AddOpenApi](/dotnet/api/microsoft.extensions.dependencyinjection.openapiservicecollectionextensions.addopenapi). +With this feature, the default OpenAPI version for generated documents is`3.1`. The version can be changed by explicitly setting the [OpenApiVersion](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions.openapiversion) property of the [OpenApiOptions](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions) in the `configureOptions` delegate parameter of [AddOpenApi](/dotnet/api/microsoft.extensions.dependencyinjection.openapiservicecollectionextensions.addopenapi): + +:::code language="csharp" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs" id="snippet_AddControllers" highlight="3"::: ```csharp builder.Services.AddOpenApi(options => @@ -25,7 +27,9 @@ builder.Services.AddOpenApi(options => }); ``` -When generating the OpenAPI document at build time, the OpenAPI version can be selected by setting the `--openapi-version` in the `OpenApiGenerateDocumentsOptions` MSBuild item. +When generating the OpenAPI document at build time, the OpenAPI version can be selected by setting the `--openapi-version` in the `OpenApiGenerateDocumentsOptions` MSBuild item: + +:::code language="csharp" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj" id="snippet_ConfigBuildTimeOpenApiDocVersion" highlight="7"::: ```xml @@ -44,6 +48,8 @@ Breaking changes in this iteration include the following: One of the most significant changes is that the `OpenApiAny` class has been dropped in favor of using `JsonNode` directly. Transformers that use `OpenApiAny` need to be updated to use `JsonNode`. The following diff shows the changes in schema transformer from .NET 9 to .NET 10: +:::code language="csharp" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/TransformerJsonNode.diff"::: + ```diff options.AddSchemaTransformer((schema, context, cancellationToken) => { @@ -74,6 +80,8 @@ ASP.NET now supports serving the generated OpenAPI document in YAML format. YAML To configure an app to serve the generated OpenAPI document in YAML format, specify the endpoint in the MapOpenApi call with a ".yaml" or ".yml" suffix, as shown in the following example: +:::code language="csharp" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs" id="snippet_ConfigOpenApiYAM" highlight="3"::: + ```csharp app.MapOpenApi("/openapi/{documentName}.yaml"); ``` diff --git a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Controllers/WeatherForecastController.cs b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Controllers/WeatherForecastController.cs new file mode 100644 index 000000000000..bd33858d25a0 --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Controllers/WeatherForecastController.cs @@ -0,0 +1,26 @@ +using Microsoft.AspNetCore.Mvc; + +namespace WebAppOpenAPI10.Controllers +{ + [ApiController] + [Route("[controller]")] + public class WeatherForecastController : ControllerBase + { + private static readonly string[] Summaries = + [ + "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" + ]; + + [HttpGet(Name = "GetWeatherForecast")] + public IEnumerable Get() + { + return Enumerable.Range(1, 5).Select(index => new WeatherForecast + { + Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)), + TemperatureC = Random.Shared.Next(-20, 55), + Summary = Summaries[Random.Shared.Next(Summaries.Length)] + }) + .ToArray(); + } + } +} diff --git a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs new file mode 100644 index 000000000000..d6601275a9ef --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs @@ -0,0 +1,29 @@ +var builder = WebApplication.CreateBuilder(args); + +// Add services to the container. +builder.Services.AddControllers(); +// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi +// +builder.Services.AddOpenApi(options => +{ + options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0; +}); +// + +var app = builder.Build(); + +// Configure the HTTP request pipeline. +// +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi("/openapi/{documentName}.yaml"); +} +// + +app.UseHttpsRedirection(); + +app.UseAuthorization(); + +app.MapControllers(); + +app.Run(); diff --git a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/TransformerJsonNode.diff b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/TransformerJsonNode.diff new file mode 100644 index 000000000000..81d5c87c2ab3 --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/TransformerJsonNode.diff @@ -0,0 +1,19 @@ +options.AddSchemaTransformer((schema, context, cancellationToken) => +{ + if (context.JsonTypeInfo.Type == typeof(WeatherForecast)) + { +- schema.Example = new OpenApiObject ++ schema.Example = new JsonObject + { +- ["date"] = new OpenApiString(DateTime.Now.AddDays(1).ToString("yyyy-MM-dd")), ++ ["date"] = DateTime.Now.AddDays(1).ToString("yyyy-MM-dd"), +- ["temperatureC"] = new OpenApiInteger(0), ++ ["temperatureC"] = 0, +- ["temperatureF"] = new OpenApiInteger(32), ++ ["temperatureF"] = 32, +- ["summary"] = new OpenApiString("Bracing"), ++ ["summary"] = "Bracing", + }; + } + return Task.CompletedTask; +}); diff --git a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WeatherForecast.cs b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WeatherForecast.cs new file mode 100644 index 000000000000..bbb212e825af --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WeatherForecast.cs @@ -0,0 +1,13 @@ +namespace WebAppOpenAPI10 +{ + public class WeatherForecast + { + public DateOnly Date { get; set; } + + public int TemperatureC { get; set; } + + public int TemperatureF => 32 + (int)(TemperatureC / 0.5556); + + public string? Summary { get; set; } + } +} diff --git a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj new file mode 100644 index 000000000000..7e430538ef37 --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj @@ -0,0 +1,15 @@ + + + + net10.0 + enable + enable + true + --openapi-version OpenApi3_0 + + + + + + + diff --git a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.http b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.http new file mode 100644 index 000000000000..848dafa8e797 --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.http @@ -0,0 +1,6 @@ +@WebAppOpenAPI10_HostAddress = http://localhost:5077 + +GET {{WebAppOpenAPI10_HostAddress}}/weatherforecast/ +Accept: application/json + +### diff --git a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/appsettings.Development.json b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/appsettings.Development.json new file mode 100644 index 000000000000..0c208ae9181e --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/appsettings.Development.json @@ -0,0 +1,8 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft.AspNetCore": "Warning" + } + } +} diff --git a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/appsettings.json b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/appsettings.json new file mode 100644 index 000000000000..10f68b8c8b4f --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/appsettings.json @@ -0,0 +1,9 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft.AspNetCore": "Warning" + } + }, + "AllowedHosts": "*" +} From 88b953980dff92b4fad8f1b71b8a174dc8eede7b Mon Sep 17 00:00:00 2001 From: wadepickett Date: Sun, 4 May 2025 17:42:24 -0700 Subject: [PATCH 2/5] fix snippet name --- aspnetcore/release-notes/aspnetcore-10/includes/openApi.md | 2 +- .../samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md index 53a151c44cd9..45e2a6308542 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md @@ -17,7 +17,7 @@ This happens when the diff --git a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj index 7e430538ef37..bf00c497c4f4 100644 --- a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj +++ b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj @@ -1,12 +1,15 @@ + net10.0 enable enable true + --openapi-version OpenApi3_0 + From 0a16ac1eb2986ef83daa54b116ff6b570118587c Mon Sep 17 00:00:00 2001 From: wadepickett Date: Sun, 4 May 2025 18:08:03 -0700 Subject: [PATCH 3/5] test .diff file type --- aspnetcore/release-notes/aspnetcore-10/includes/openApi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md index 45e2a6308542..ad9b3ab0d102 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md @@ -48,7 +48,7 @@ Breaking changes in this iteration include the following: One of the most significant changes is that the `OpenApiAny` class has been dropped in favor of using `JsonNode` directly. Transformers that use `OpenApiAny` need to be updated to use `JsonNode`. The following diff shows the changes in schema transformer from .NET 9 to .NET 10: -:::code language="csharp" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/TransformerJsonNode.diff"::: +:::code language="diff" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/TransformerJsonNode.diff"::: ```diff options.AddSchemaTransformer((schema, context, cancellationToken) => From be35b3ce1e530104b3fcc183ba4e974dacaeaef3 Mon Sep 17 00:00:00 2001 From: wadepickett Date: Sun, 4 May 2025 18:22:31 -0700 Subject: [PATCH 4/5] test .cs but lang set to diff --- .../aspnetcore-10/includes/openApi.md | 19 +++---------------- ...erJsonNode.diff => TransformerJsonNode.cs} | 0 2 files changed, 3 insertions(+), 16 deletions(-) rename aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/{TransformerJsonNode.diff => TransformerJsonNode.cs} (100%) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md index ad9b3ab0d102..7c9ff5a0754a 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md @@ -19,22 +19,9 @@ With this feature, the default OpenAPI version for generated documents is`3.1`. :::code language="csharp" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs" id="snippet_DefaultOpenApiVersion" highlight="3"::: -```csharp -builder.Services.AddOpenApi(options => -{ - // Specify the OpenAPI version to use. - options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0; -}); -``` - When generating the OpenAPI document at build time, the OpenAPI version can be selected by setting the `--openapi-version` in the `OpenApiGenerateDocumentsOptions` MSBuild item: -:::code language="csharp" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj" id="snippet_ConfigBuildTimeOpenApiDocVersion" highlight="7"::: - -```xml - - --openapi-version OpenApi3_0 -``` +:::code language="xml" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/WebAppOpenAPI10.csproj" id="snippet_ConfigBuildTimeOpenApiDocVersion" highlight="7"::: OpenAPI 3.1 support was primarily added in the following [PR](https://github.com/dotnet/aspnetcore/pull/59480). @@ -46,9 +33,9 @@ Breaking changes in this iteration include the following: * Entities within the OpenAPI document, like operations and parameters, are typed as interfaces. Concrete implementations exist for the inlined and referenced variants of an entity. For example, an `IOpenApiSchema` can either be an inlined `OpenApiSchema` or an `OpenApiSchemaReference` that points to a schema defined elsewhere in the document. * The `Nullable` property has been removed from the `OpenApiSchema` type. To determine if a type is nullable, evaluate if the `OpenApiSchema.Type` property sets `JsonSchemaType.Null`. -One of the most significant changes is that the `OpenApiAny` class has been dropped in favor of using `JsonNode` directly. Transformers that use `OpenApiAny` need to be updated to use `JsonNode`. The following diff shows the changes in schema transformer from .NET 9 to .NET 10: +One of the most significant changes is that the `OpenApiAny` class has been dropped in favor of using `JsonNode` directly. Transformers that use `OpenApiAny` need to be updated to use `JsonNode`. The following diff shows the changes in schema transformer from .NET 9 to .NET 10: -:::code language="diff" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/TransformerJsonNode.diff"::: +:::code language="diff" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/TransformerJsonNode.cs"::: ```diff options.AddSchemaTransformer((schema, context, cancellationToken) => diff --git a/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/TransformerJsonNode.diff b/aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/TransformerJsonNode.cs similarity index 100% rename from aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/TransformerJsonNode.diff rename to aspnetcore/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/TransformerJsonNode.cs From b569a32d24822b5fabb8682224e38f1bd06b3dfa Mon Sep 17 00:00:00 2001 From: wadepickett Date: Sun, 4 May 2025 18:33:18 -0700 Subject: [PATCH 5/5] fixed diff --- .../aspnetcore-10/includes/openApi.md | 28 +------------------ 1 file changed, 1 insertion(+), 27 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md index 7c9ff5a0754a..7ad3cfe81732 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md @@ -37,28 +37,6 @@ One of the most significant changes is that the `OpenApiAny` class has been drop :::code language="diff" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/TransformerJsonNode.cs"::: -```diff -options.AddSchemaTransformer((schema, context, cancellationToken) => -{ - if (context.JsonTypeInfo.Type == typeof(WeatherForecast)) - { -- schema.Example = new OpenApiObject -+ schema.Example = new JsonObject - { -- ["date"] = new OpenApiString(DateTime.Now.AddDays(1).ToString("yyyy-MM-dd")), -+ ["date"] = DateTime.Now.AddDays(1).ToString("yyyy-MM-dd"), -- ["temperatureC"] = new OpenApiInteger(0), -+ ["temperatureC"] = 0, -- ["temperatureF"] = new OpenApiInteger(32), -+ ["temperatureF"] = 32, -- ["summary"] = new OpenApiString("Bracing"), -+ ["summary"] = "Bracing", - }; - } - return Task.CompletedTask; -}); -``` - Note that these changes are necessary even when only configuring the OpenAPI version to 3.0. ### OpenAPI in YAML @@ -67,11 +45,7 @@ ASP.NET now supports serving the generated OpenAPI document in YAML format. YAML To configure an app to serve the generated OpenAPI document in YAML format, specify the endpoint in the MapOpenApi call with a ".yaml" or ".yml" suffix, as shown in the following example: -:::code language="csharp" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs" id="snippet_ConfigOpenApiYAM" highlight="3"::: - -```csharp -app.MapOpenApi("/openapi/{documentName}.yaml"); -``` +:::code language="csharp" source="~/release-notes/aspnetcore-10/samples/WebAppOpenAPI10/Program.cs" id="snippet_ConfigOpenApiYAML" highlight="3"::: Support for: