From b3967d37c7b0371dd1e6235a33af12ffc0915a0f Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Sun, 5 Oct 2025 17:21:14 -0400 Subject: [PATCH] docs: adds the v3 upgrade guide Signed-off-by: Vincent Biret --- docs/upgrade-guide-3.md | 386 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 386 insertions(+) create mode 100644 docs/upgrade-guide-3.md diff --git a/docs/upgrade-guide-3.md b/docs/upgrade-guide-3.md new file mode 100644 index 000000000..15c7e7748 --- /dev/null +++ b/docs/upgrade-guide-3.md @@ -0,0 +1,386 @@ +# 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. + +## 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: + +```csharp +// v2.x +document.SerializeAsV31(writer); + +// v3.0 +document.SerializeAsV31(writer); +document.SerializeAsV32(writer); // New! +``` + +### OpenApiSpecVersion Enum Update + +A new version constant has been added: + +```csharp +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: + +```csharp +// v2.x +public IDictionary? Content { get; set; } + +// v3.0 +public IDictionary? Content { get; set; } +``` + +### New Media Type Properties + +The `IOpenApiMediaType` interface includes additional properties for enhanced functionality: + +```csharp +public interface IOpenApiMediaType +{ + IDictionary? Encoding { get; } + JsonNode? Example { get; } + IDictionary? Examples { get; } + OpenApiEncoding? ItemEncoding { get; } // New! + IOpenApiSchema? ItemSchema { get; } // New! + IList? PrefixEncoding { get; } // New! + IOpenApiSchema? Schema { get; } +} +``` + +### MediaTypes in Components + +Components now support reusable media types: + +```csharp +public class OpenApiComponents +{ + public IDictionary? MediaTypes { get; set; } // New! + // ... other existing properties +} +``` + +## Enhanced Example Support + +### New Example Properties + +Example objects now support additional data representation options: + +```csharp +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: + +```csharp +public interface IOpenApiSecurityScheme +{ + bool Deprecated { get; } // New! + // ... other existing properties +} +``` + +### Device Authorization Flow + +OAuth flows now support device authorization: + +```csharp +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: + +```csharp +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: + +```csharp +// 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: + +```csharp +// 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: + +```csharp +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: + +```csharp +public class OpenApiDocument +{ + public Uri? Self { get; set; } // New! + // ... other existing properties +} +``` + +## Parameter Location Enhancements + +### New Parameter Locations + +Additional parameter locations are now supported: + +```csharp +public enum ParameterLocation +{ + Query = 0, + Header = 1, + Path = 2, + Cookie = 3, + QueryString = 4, // New! +} +``` + +### New Parameter Styles + +```csharp +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 + +```csharp +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: + +```csharp +// v2.x +public virtual void Visit(OpenApiMediaType mediaType) { } + +// v3.0 +public virtual void Visit(IOpenApiMediaType mediaType) { } +``` + +## Version Detection + +### New Version Detection Method + +```csharp +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`: + +```csharp +// Before +public IDictionary? Content { get; set; } + +// After +public IDictionary? Content { get; set; } +``` + +### 2. Update XML Object Usage + +Replace boolean properties with the new enum-based approach: + +```csharp +// 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: + +```csharp +// 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: + +```csharp +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](https://github.com/microsoft/OpenAPI.NET/issues). The team looks forward to hearing about your experience with OpenAPI.NET v3.0 and OpenAPI v3.2 support!