Skip to content

docs: minor updates to the upgrade guide #2441

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 11, 2025
Merged

docs: minor updates to the upgrade guide #2441

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ac42709
docs: minor updates to the upgrade guide
baywet Jul 11, 2025
3cab6f9
docs: removes preview phrasing from upgrade docs
baywet Jul 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 8 additions & 21 deletions docs/upgrade-guide-2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -86,11 +86,11 @@ var mySchema = new OpenApiSchema();
mySchema.AnyOf.Add(otherSchema);

// one solution
mySchema.AnyOf ??= [];
mySchema.AnyOf ??= new List<IOpenApiSchema>();
mySchema.AnyOf.Add(otherSchema);

// alternative
mySchema.AnyOf = [otherSchema];
mySchema.AnyOf = new List<IOpenApiSchema> { otherSchema };
```

## Reduced Dependencies
Expand Down Expand Up @@ -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:**

Expand All @@ -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<OpenApiSchema> instead of IList<OpenApiSchema>
```

### 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`.
Expand Down Expand Up @@ -432,7 +419,7 @@ public class OpenApiComponents : IOpenApiSerializable, IOpenApiExtensible
/// <summary>
/// An object to hold reusable <see cref="OpenApiPathItem"/> Object.
/// </summary>
public IDictionary<string, OpenApiPathItem>? PathItems { get; set; } = new Dictionary<string, OpenApiPathItem>();
public IDictionary<string, OpenApiPathItem>? PathItems { get; set; }
}
```

Expand All @@ -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"
};
Expand Down Expand Up @@ -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);

```

Expand All @@ -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
Expand Down
Loading