From fa44e88780d9ff33b40388519807812226a5df16 Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Sat, 12 Apr 2025 09:10:58 -0700 Subject: [PATCH 1/3] Explain OpenAPI representation of int and long types in .NET 10 --- aspnetcore/release-notes/aspnetcore-10.0.md | 2 -- aspnetcore/release-notes/aspnetcore-10/includes/openApi.md | 7 +++++++ 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-10.0.md b/aspnetcore/release-notes/aspnetcore-10.0.md index b08561850278..c4dc4c6f9545 100644 --- a/aspnetcore/release-notes/aspnetcore-10.0.md +++ b/aspnetcore/release-notes/aspnetcore-10.0.md @@ -51,8 +51,6 @@ This section describes new features for OpenAPI. [!INCLUDE[](~/release-notes/aspnetcore-10/includes/OpenApiPopulateXMLDocComments.md)] -[!INCLUDE[](~/release-notes/aspnetcore-10/includes/OpenApiNetV2Prev7.md)] - [!INCLUDE[](~/release-notes/aspnetcore-10/includes/webapiaotTemplateAddedOpenAPI.md)] ## Authentication and authorization diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md index bae9c2b0957f..6b5015555858 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md @@ -11,6 +11,9 @@ Some of the changes you will see in the generated OpenAPI document include: * Nullable types no longer have the `nullable: true` property in the schema. * Instead of a `nullable: true` property, they have a `type` keyword whose value is an array that includes `null` as one of the types. +* Properties or parameters defined as a C# `int` or `long` may now appear in the generated OpenAPI document without the `type: integer` field +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 applications. If you want C# `int` and `long` to be represented in the OpenAPI as `type: integer`, you should 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). @@ -34,6 +37,10 @@ OpenAPI 3.1 support was primarily added in the following [PR](https://github.com ### OpenAPI 3.1 breaking changes Support for OpenAPI 3.1 requires an update to the underlying OpenAPI.NET library to a new major version, 2.0. This new version has some breaking changes from the previous version. The breaking changes may impact apps if they have any document, operation, or schema transformers. +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: From 50d78ecc239512e2bcf61a340de4ec818bc10280 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Sun, 13 Apr 2025 07:47:19 -1000 Subject: [PATCH 2/3] Update OpenAPI document generation details (#35215) * Update OpenAPI document generation details * Format openApi.md for better readability --- aspnetcore/release-notes/aspnetcore-10/includes/openApi.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md index 6b5015555858..5ba2dfd20177 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md @@ -11,9 +11,9 @@ Some of the changes you will see in the generated OpenAPI document include: * Nullable types no longer have the `nullable: true` property in the schema. * Instead of a `nullable: true` property, they have a `type` keyword whose value is an array that includes `null` as one of the types. -* Properties or parameters defined as a C# `int` or `long` may now appear in the generated OpenAPI document without the `type: integer` field +* Properties or parameters defined as a C# `int` or `long` now appear in the generated OpenAPI document without the `type: integer` field 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 applications. If you want C# `int` and `long` to be represented in the OpenAPI as `type: integer`, you should set the property to `Strict`. +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 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). From 7bfd410dd5a44da639bb28bbcc7c9d2f54fe16f6 Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Mon, 14 Apr 2025 08:33:11 -0500 Subject: [PATCH 3/3] Apply suggestions from PR review Co-authored-by: Martin Costello --- 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 5ba2dfd20177..65e98cfad738 100644 --- a/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md +++ b/aspnetcore/release-notes/aspnetcore-10/includes/openApi.md @@ -13,7 +13,7 @@ Some of the changes you will see in the generated OpenAPI document include: * Instead of a `nullable: true` property, they have a `type` keyword whose value is an array that includes `null` as one of the types. * Properties or parameters defined as a C# `int` or `long` now appear in the generated OpenAPI document without the `type: integer` field 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 as `type: integer`, set the property to `Strict`. +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).