Skip to content

Latest commit

 

History

History
398 lines (295 loc) · 9.78 KB

upgrade-guide-3.md

File metadata and controls

398 lines (295 loc) · 9.78 KB

Upgrade guide to OpenAPI.NET 3.0

Introduction

We are excited to announce OpenAPI.NET v3.0! This major update introduces support for OpenAPI v3.2 specification along with several API enhancements and refinements to the existing model architecture.

Warning

This is a major version update that includes breaking changes. Please review this guide carefully before upgrading.

Integrations with ASP.NET Core

If you are using this library with AspNetCore OpenAPI versions < 10.0 then you must remain on version 1.x as it's not compatible with version 3 or above of this library.

If you are using this library with AspNetCore OpenAPI versions = 10.X then you must remain on version 2.x as it's not compatible with version 3 or above of this library.

If you are using this library with Swashbuckle.AspNetCore version < 10.0 then you must remain on version 1.x as it's not compatible with version 3 or above of this library.

If you are using this library with Swashbuckle.AspNetCore version = 10.X then you must remain on version 2.x as it's not compatible with version 3 or above of this library.

The latest support policy information for this library, and integration with ASP.NET Core can be found on the contributing documentation.

OpenAPI v3.2 Support

The primary focus of OpenAPI.NET v3.0 is adding comprehensive support for OpenAPI specification v3.2. This includes new serialization methods, enhanced model properties, and expanded functionality across the entire API surface.

New Serialization Methods

All serializable components now include a SerializeAsV32 method alongside the existing serialization methods:

// v2.x
document.SerializeAsV31(writer);

// v3.0
document.SerializeAsV31(writer);
document.SerializeAsV32(writer); // New!

OpenApiSpecVersion Enum Update

A new version constant has been added:

public enum OpenApiSpecVersion
{
    OpenApi2_0 = 0,
    OpenApi3_0 = 1,
    OpenApi3_1 = 2,
    OpenApi3_2 = 3,  // New!
}

Enhanced Media Type Support

IOpenApiMediaType Interface

Media types are now represented by the IOpenApiMediaType interface, providing better abstraction and consistency across the API:

// v2.x
public IDictionary<string, OpenApiMediaType>? Content { get; set; }

// v3.0
public IDictionary<string, IOpenApiMediaType>? Content { get; set; }

New Media Type Properties

The IOpenApiMediaType interface includes additional properties for enhanced functionality:

public interface IOpenApiMediaType
{
    IDictionary<string, OpenApiEncoding>? Encoding { get; }
    JsonNode? Example { get; }
    IDictionary<string, IOpenApiExample>? Examples { get; }
    OpenApiEncoding? ItemEncoding { get; }        // New!
    IOpenApiSchema? ItemSchema { get; }           // New!
    IList<OpenApiEncoding>? PrefixEncoding { get; } // New!
    IOpenApiSchema? Schema { get; }
}

MediaTypes in Components

Components now support reusable media types:

public class OpenApiComponents
{
    public IDictionary<string, IOpenApiMediaType>? MediaTypes { get; set; } // New!
    // ... other existing properties
}

Enhanced Example Support

New Example Properties

Example objects now support additional data representation options:

public class OpenApiExample : IOpenApiExample
{
    public JsonNode? DataValue { get; set; }      // New!
    public string? SerializedValue { get; set; }  // New!
    public string? ExternalValue { get; set; }
    public JsonNode? Value { get; set; }
    // ... other properties
}

Security Scheme Enhancements

Deprecated Property

Security schemes now support a deprecated flag:

public interface IOpenApiSecurityScheme
{
    bool Deprecated { get; }  // New!
    // ... other existing properties
}

Device Authorization Flow

OAuth flows now support device authorization:

public class OpenApiOAuthFlows
{
    public OpenApiOAuthFlow? DeviceAuthorization { get; set; }  // New!
    // ... other existing flows
}

public class OpenApiOAuthFlow
{
    public Uri? DeviceAuthorizationUrl { get; set; }  // New!
    // ... other existing properties
}

Tag System Improvements

Hierarchical Tags

Tags now support hierarchical organization with enhanced metadata:

public interface IOpenApiTag
{
    string? Kind { get; }                    // New!
    string? Summary { get; }                 // New!
    OpenApiTagReference? Parent { get; }     // New!
    string? Name { get; }
    // ... other existing properties
}

Response Enhancements

Summary Support

Responses now implement IOpenApiSummarizedElement and support summary text:

// v2.x
public interface IOpenApiResponse : IOpenApiDescribedElement, ...
{
    // No summary support
}

// v3.0
public interface IOpenApiResponse : IOpenApiDescribedElement, 
    IOpenApiSummarizedElement, ...  // New!
{
    // Inherits Summary property from IOpenApiSummarizedElement
}

XML Improvements

Enhanced Node Type Support

The XML object has been refactored to use a more flexible node type system:

// v2.x
public class OpenApiXml
{
    public bool Attribute { get; set; }  // Removed!
    public bool Wrapped { get; set; }    // Removed!
}

// v3.0
public class OpenApiXml
{
    public OpenApiXmlNodeType? NodeType { get; set; }  // New!
}

public enum OpenApiXmlNodeType
{
    Element = 0,
    Attribute = 1,
    Text = 2,
    Cdata = 3,
    None = 4,
}

Discriminator Enhancements

Default Mapping Support

Discriminators now support default mapping scenarios:

public class OpenApiDiscriminator
{
    public OpenApiSchemaReference? DefaultMapping { get; set; }  // New!
    // ... other existing properties
}

Document Enhancements

Self-Reference Support

Documents can now specify their own identity URI:

public class OpenApiDocument
{
    public Uri? Self { get; set; }  // New!
    // ... other existing properties
}

Parameter Location Enhancements

New Parameter Locations

Additional parameter locations are now supported:

public enum ParameterLocation
{
    Query = 0,
    Header = 1,
    Path = 2,
    Cookie = 3,
    QueryString = 4,  // New!
}

New Parameter Styles

public enum ParameterStyle
{
    Matrix = 0,
    Label = 1,
    Form = 2,
    Simple = 3,
    SpaceDelimited = 4,
    PipeDelimited = 5,
    DeepObject = 6,
    Cookie = 7,  // New!
}

Reference Type Enhancements

New Reference Types

public enum ReferenceType
{
    Schema = 0,
    Response = 1,
    Parameter = 2,
    Example = 3,
    RequestBody = 4,
    Header = 5,
    SecurityScheme = 6,
    Link = 7,
    Callback = 8,
    Tag = 9,
    PathItem = 10,
    MediaType = 11,  // New!
}

Visitor Pattern Updates

Interface-Based Visiting

The visitor pattern now works with interface types for better abstraction:

// v2.x
public virtual void Visit(OpenApiMediaType mediaType) { }

// v3.0
public virtual void Visit(IOpenApiMediaType mediaType) { }

Version Detection

New Version Detection Method

public static class VersionService
{
    public static bool is3_2(this string version) { }  // New!
    // ... other existing version methods
}

Migration Steps

1. Update Media Type References

Replace concrete OpenApiMediaType references with IOpenApiMediaType:

// Before
public IDictionary<string, OpenApiMediaType>? Content { get; set; }

// After
public IDictionary<string, IOpenApiMediaType>? Content { get; set; }

2. Update XML Object Usage

Replace boolean properties with the new enum-based approach:

// Before
var xml = new OpenApiXml
{
    Attribute = true,
    Wrapped = false
};

// After
var xml = new OpenApiXml
{
    NodeType = OpenApiXmlNodeType.Attribute
};

3. Update Visitor Implementations

Update visitor methods to use interface types:

// Before
public override void Visit(OpenApiMediaType mediaType) { /* ... */ }

// After
public override void Visit(IOpenApiMediaType mediaType) { /* ... */ }

4. Add v3.2 Serialization Support

If you have custom serialization logic, add support for v3.2:

public void SerializeAsV32(IOpenApiWriter writer)
{
    // Implement v3.2 specific serialization
    SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_2);
}

Breaking Changes Summary

  1. Media Type Abstraction: OpenApiMediaType replaced with IOpenApiMediaType interface in collection properties
  2. XML Object Refactoring: Attribute and Wrapped boolean properties replaced with NodeType enum
  3. Visitor Pattern: Methods now accept interface types instead of concrete types
  4. Response Interface: IOpenApiResponse now extends IOpenApiSummarizedElement

New Features Summary

  1. OpenAPI v3.2 Support: Full serialization and model support
  2. Enhanced Media Types: New properties for encoding and schema support
  3. Hierarchical Tags: Support for tag organization with kind, summary, and parent relationships
  4. Security Enhancements: Deprecated flag and device authorization flow support
  5. Enhanced Examples: New data value and serialized value properties
  6. Document Self-Reference: Support for document identity URIs
  7. Extended Parameter Support: New locations and styles for parameters

Feedback

If you have any feedback please file a new GitHub issue. The team looks forward to hearing about your experience with OpenAPI.NET v3.0 and OpenAPI v3.2 support!