diff --git a/.azure-pipelines/ci-build.yml b/.azure-pipelines/ci-build.yml index 1f4c7a41e..8921e7112 100644 --- a/.azure-pipelines/ci-build.yml +++ b/.azure-pipelines/ci-build.yml @@ -7,6 +7,7 @@ trigger: include: - main - support/v1 + - support/v2 tags: include: - 'v*' @@ -15,6 +16,7 @@ pr: include: - main - support/v1 + - support/v2 variables: buildPlatform: 'Any CPU' @@ -307,6 +309,7 @@ extends: publishFeedCredentials: 'OpenAPI Nuget Connection' - deployment: create_github_release + condition: and(contains(variables['build.SourceBranch'], 'refs/tags/v'), succeeded()) templateContext: type: releaseJob isProduction: true diff --git a/.github/policies/OpenAPI.NET-branch-protection.yml b/.github/policies/OpenAPI.NET-branch-protection.yml index 6deeb87fa..2d8fd2a73 100644 --- a/.github/policies/OpenAPI.NET-branch-protection.yml +++ b/.github/policies/OpenAPI.NET-branch-protection.yml @@ -81,3 +81,39 @@ configuration: # Restrict who can dismiss pull request reviews. boolean restrictsReviewDismissals: false + - branchNamePattern: support/v2 + # This branch pattern applies to the following branches as of approximately 02/27/2025 15:28:20: + # support/v1 + + # Specifies whether this branch can be deleted. boolean + allowsDeletions: false + # Specifies whether forced pushes are allowed on this branch. boolean + allowsForcePushes: false + # Specifies whether new commits pushed to the matching branches dismiss pull request review approvals. boolean + dismissStaleReviews: true + # Specifies whether admins can overwrite branch protection. boolean + isAdminEnforced: true + # Indicates whether "Require a pull request before merging" is enabled. boolean + requiresPullRequestBeforeMerging: true + # Specifies the number of pull request reviews before merging. int (0-6). Should be null/empty if PRs are not required + requiredApprovingReviewsCount: 1 + # Require review from Code Owners. Requires requiredApprovingReviewsCount. boolean + requireCodeOwnersReview: true + # Are commits required to be signed. boolean. TODO: all contributors must have commit signing on local machines. + requiresCommitSignatures: false + # Are conversations required to be resolved before merging? boolean + requiresConversationResolution: true + # Are merge commits prohibited from being pushed to this branch. boolean + requiresLinearHistory: false + # Required status checks to pass before merging. Values can be any string, but if the value does not correspond to any existing status check, the status check will be stuck on pending for status since nothing exists to push an actual status + requiredStatusChecks: + - license/cla + - CodeQL + - Continuous Integration + # Require branches to be up to date before merging. boolean + requiresStrictStatusChecks: false + # Indicates whether there are restrictions on who can push. boolean. Should be set with whoCanPush. + restrictsPushes: false + # Restrict who can dismiss pull request reviews. boolean + restrictsReviewDismissals: false + diff --git a/.github/release-please.yml b/.github/release-please.yml index c821fc166..ce23f6ec0 100644 --- a/.github/release-please.yml +++ b/.github/release-please.yml @@ -3,5 +3,8 @@ primaryBranch: main handleGHRelease: true branches: - branch: support/v1 + manifest: true + handleGHRelease: true + - branch: support/v2 manifest: true handleGHRelease: true \ No newline at end of file diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index 9839c4904..ac897fd86 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -2,7 +2,7 @@ name: CodeQL Analysis on: push: - branches: [ main, support/v1 ] + branches: [ main, support/v1, support/v2 ] pull_request: schedule: - cron: '0 8 * * *' diff --git a/.github/workflows/release-please-gha.yml b/.github/workflows/release-please-gha.yml index a730548a2..173b15cbb 100644 --- a/.github/workflows/release-please-gha.yml +++ b/.github/workflows/release-please-gha.yml @@ -15,6 +15,7 @@ on: branches: - main - support/v1 + - support/v2 jobs: release: 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! diff --git a/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report-github.md b/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report-github.md index 5c8d571e6..51834bbcf 100644 --- a/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report-github.md +++ b/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report-github.md @@ -1,18 +1,18 @@ ``` -BenchmarkDotNet v0.15.2, Linux Ubuntu 24.04.2 LTS (Noble Numbat) -AMD EPYC 7763, 1 CPU, 4 logical and 2 physical cores -.NET SDK 8.0.413 - [Host] : .NET 8.0.19 (8.0.1925.36514), X64 RyuJIT AVX2 - ShortRun : .NET 8.0.19 (8.0.1925.36514), X64 RyuJIT AVX2 +BenchmarkDotNet v0.15.4, Windows 11 (10.0.26200.6584) +11th Gen Intel Core i7-1185G7 3.00GHz, 1 CPU, 8 logical and 4 physical cores +.NET SDK 8.0.414 + [Host] : .NET 8.0.20 (8.0.20, 8.0.2025.41914), X64 RyuJIT x86-64-v4 + ShortRun : .NET 8.0.20 (8.0.20, 8.0.2025.41914), X64 RyuJIT x86-64-v4 Job=ShortRun IterationCount=3 LaunchCount=1 WarmupCount=3 ``` -| Method | Mean | Error | StdDev | Gen0 | Gen1 | Gen2 | Allocated | -|------------- |---------------:|--------------:|------------:|-----------:|-----------:|----------:|-------------:| -| PetStoreYaml | 529.5 μs | 62.50 μs | 3.43 μs | 23.4375 | 3.9063 | - | 387.26 KB | -| PetStoreJson | 240.8 μs | 15.69 μs | 0.86 μs | 13.6719 | 1.9531 | - | 249.1 KB | -| GHESYaml | 1,097,576.6 μs | 100,584.42 μs | 5,513.37 μs | 26000.0000 | 20000.0000 | 3000.0000 | 384492.38 KB | -| GHESJson | 516,328.2 μs | 87,964.22 μs | 4,821.62 μs | 16000.0000 | 9000.0000 | 2000.0000 | 245957.5 KB | +| Method | Mean | Error | StdDev | Gen0 | Gen1 | Gen2 | Allocated | +|------------- |---------------:|-------------:|-------------:|-----------:|-----------:|----------:|-------------:| +| PetStoreYaml | 525.7 μs | 1,392.5 μs | 76.33 μs | 62.5000 | 11.7188 | - | 387.72 KB | +| PetStoreJson | 241.1 μs | 706.2 μs | 38.71 μs | 40.0391 | 8.7891 | - | 249.86 KB | +| GHESYaml | 1,126,435.6 μs | 361,261.8 μs | 19,801.98 μs | 66000.0000 | 22000.0000 | 4000.0000 | 384551.24 KB | +| GHESJson | 970,225.6 μs | 187,943.8 μs | 10,301.84 μs | 40000.0000 | 16000.0000 | 3000.0000 | 246022.93 KB | diff --git a/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report.csv b/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report.csv index 1a21885c7..2d7c82729 100644 --- a/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report.csv +++ b/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report.csv @@ -1,5 +1,5 @@ Method,Job,AnalyzeLaunchVariance,EvaluateOverhead,MaxAbsoluteError,MaxRelativeError,MinInvokeCount,MinIterationTime,OutlierMode,Affinity,EnvironmentVariables,Jit,LargeAddressAware,Platform,PowerPlanMode,Runtime,AllowVeryLargeObjects,Concurrent,CpuGroups,Force,HeapAffinitizeMask,HeapCount,NoAffinitize,RetainVm,Server,Arguments,BuildConfiguration,Clock,EngineFactory,NuGetReferences,Toolchain,IsMutator,InvocationCount,IterationCount,IterationTime,LaunchCount,MaxIterationCount,MaxWarmupIterationCount,MemoryRandomization,MinIterationCount,MinWarmupIterationCount,RunStrategy,UnrollFactor,WarmupCount,Mean,Error,StdDev,Gen0,Gen1,Gen2,Allocated -PetStoreYaml,ShortRun,False,Default,Default,Default,Default,Default,Default,1111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,529.5 μs,62.50 μs,3.43 μs,23.4375,3.9063,0.0000,387.26 KB -PetStoreJson,ShortRun,False,Default,Default,Default,Default,Default,Default,1111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,240.8 μs,15.69 μs,0.86 μs,13.6719,1.9531,0.0000,249.1 KB -GHESYaml,ShortRun,False,Default,Default,Default,Default,Default,Default,1111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,"1,097,576.6 μs","100,584.42 μs","5,513.37 μs",26000.0000,20000.0000,3000.0000,384492.38 KB -GHESJson,ShortRun,False,Default,Default,Default,Default,Default,Default,1111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,"516,328.2 μs","87,964.22 μs","4,821.62 μs",16000.0000,9000.0000,2000.0000,245957.5 KB +PetStoreYaml,ShortRun,False,Default,Default,Default,Default,Default,Default,11111111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,525.7 μs,"1,392.5 μs",76.33 μs,62.5000,11.7188,0.0000,387.72 KB +PetStoreJson,ShortRun,False,Default,Default,Default,Default,Default,Default,11111111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,241.1 μs,706.2 μs,38.71 μs,40.0391,8.7891,0.0000,249.86 KB +GHESYaml,ShortRun,False,Default,Default,Default,Default,Default,Default,11111111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,"1,126,435.6 μs","361,261.8 μs","19,801.98 μs",66000.0000,22000.0000,4000.0000,384551.24 KB +GHESJson,ShortRun,False,Default,Default,Default,Default,Default,Default,11111111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,"970,225.6 μs","187,943.8 μs","10,301.84 μs",40000.0000,16000.0000,3000.0000,246022.93 KB diff --git a/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report.html b/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report.html index 5661bcdf8..f76302db4 100644 --- a/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report.html +++ b/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report.html @@ -2,7 +2,7 @@ -performance.Descriptions-20250820-142630 +performance.Descriptions-20251003-105951