diff --git a/docs/upgrade-guide-2.md b/docs/upgrade-guide-2.md index f7ea5ef2c..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 @@ -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 @@ -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:** @@ -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