From ac427095be3ec52d5538c0fe77c71d0343aaa286 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 11 Jul 2025 08:31:49 -0400 Subject: [PATCH 1/2] docs: minor updates to the upgrade guide Signed-off-by: Vincent Biret --- docs/upgrade-guide-2.md | 25 ++++++------------------- 1 file changed, 6 insertions(+), 19 deletions(-) diff --git a/docs/upgrade-guide-2.md b/docs/upgrade-guide-2.md index f7ea5ef2c..bb93b3d9f 100644 --- a/docs/upgrade-guide-2.md +++ b/docs/upgrade-guide-2.md @@ -86,11 +86,11 @@ var mySchema = new OpenApiSchema(); mySchema.AnyOf.Add(otherSchema); // one solution -mySchema.AnyOf ??= []; +mySchema.AnyOf ??= new List(); mySchema.AnyOf.Add(otherSchema); // alternative -mySchema.AnyOf = [otherSchema]; +mySchema.AnyOf = new List { otherSchema }; ``` ## Reduced Dependencies @@ -266,19 +266,6 @@ var document = new OpenApiDocument var componentA = document.Components["A"]; ``` -### Collections are implementations - -Any collection used by the model now documents using the implementation type instead of the interface. This facilitates the usage of new language features such as collections initialization. - -```csharp -var schema = new OpenApiSchema(); - -// 1.X: does not compile due to the lack of implementation type -// 2.X: compiles successfully -schema.AnyOf = []; -// now a List instead of IList -``` - ### Ephemeral object properties are now in Metadata In version 1.X applications could add ephemeral properties to some of the models from the libraries. These properties would be carried along in an "Annotations" property, but not serialized. This is especially helpful when building integrations that build document in multiple phases and need additional context to complete the work. The property is now named metadata to avoid any confusion with other terms. The parent interface has also been renamed from `IOpenApiAnnotatable` to `IMetadataContainer`. @@ -432,7 +419,7 @@ public class OpenApiComponents : IOpenApiSerializable, IOpenApiExtensible /// /// An object to hold reusable Object. /// - public IDictionary? PathItems { get; set; } = new Dictionary(); + public IDictionary? PathItems { get; set; } } ``` @@ -441,7 +428,7 @@ public class OpenApiComponents : IOpenApiSerializable, IOpenApiExtensible Through the use of proxy objects in order to represent references, it is now possible to set the Summary and Description property on an object that is a reference. This was previously not possible. ```csharp -var parameter = new OpenApiParameterReference("id", hostdocument) +var parameter = new OpenApiParameterReference("id", hostDocument) { Description = "Customer Id" }; @@ -511,7 +498,7 @@ The `SerializeAs()` method simplifies serialization scenarios, making it easier ```csharp OpenApiDocument document = new OpenApiDocument(); -string json = document.SerializeAs(OpenApiSpecVersion.OpenApi3_0, OpenApiConstants.Json); +string json = await document.SerializeAsync(OpenApiSpecVersion.OpenApi3_0, OpenApiConstants.Json); ``` @@ -526,7 +513,7 @@ string json = document.SerializeAs(OpenApiSpecVersion.OpenApi3_0, OpenApiConstan var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, OpenApiFormat.Json); // After (2.0) -var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, OpenApiConstants.Json); +var outputString = await openApiDocument.SerializeAsync(OpenApiSpecVersion.OpenApi2_0, OpenApiConstants.Json); ``` ### OpenApiSchema's Type property is now a flaggable enum From 3cab6f96aa0f58646d998ecdeb1b7570674b1926 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 11 Jul 2025 08:57:16 -0400 Subject: [PATCH 2/2] docs: removes preview phrasing from upgrade docs Signed-off-by: Vincent Biret --- docs/upgrade-guide-2.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/upgrade-guide-2.md b/docs/upgrade-guide-2.md index bb93b3d9f..dbee36f03 100644 --- a/docs/upgrade-guide-2.md +++ b/docs/upgrade-guide-2.md @@ -8,7 +8,7 @@ ms.topic: conceptual # Introduction -We are excited to announce the preview of a new version of the OpenAPI.NET library! +We are excited to announce the new version of the OpenAPI.NET library! OpenAPI.NET v2 is a major update to the OpenAPI.NET library. This release includes a number of performance improvements, API enhancements, and support for OpenAPI v3.1. ## The biggest update ever @@ -251,7 +251,7 @@ parameter.Extensions.Add("x-foo", new JsonNodeExtension(openApiObject)); ### Enable Null Reference Type Support -Version 2.0 preview 13 introduces support for null reference types, which improves type safety and reduces the likelihood of null reference exceptions. +Version 2.0 introduces support for null reference types, which improves type safety and reduces the likelihood of null reference exceptions. **Example:**