performance.Descriptions-20251023-154034

diff --git a/.azure-pipelines/ci-build.yml b/.azure-pipelines/ci-build.yml index 1f4c7a41e..53b181b22 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 @@ -469,4 +472,8 @@ extends: -t "$(REGISTRY)/$(IMAGE_NAME):${VERSION}" \ "$(Pipeline.Workspace)" displayName: 'Build and Push Release Image' - condition: contains(variables['Build.SourceBranch'], 'refs/tags/v') \ No newline at end of file + condition: contains(variables['Build.SourceBranch'], 'refs/tags/v') + +# once the nuget has been released, fill this form to get the public documentation updated. +# https://dev.azure.com/msft-skilling/Content/_workitems/create/User%20Story?templateId=39fb91e3-64a2-4c8a-83db-b2bdf3603dd3&ownerId=c4a28f90-17ae-4384-b514-7273392b082b +# https://learn.microsoft.com/en-us/dotnet/api/microsoft.openapi diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..12f65c04f --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,63 @@ +# Copilot Instructions + +## Commit Message Format + +Always use conventional commits format when creating commits. Follow this structure: + +``` +(): + +[optional body] + +[optional footer(s)] +``` + +### Types + +- **feat**: A new feature +- **fix**: A bug fix +- **docs**: Documentation only changes +- **style**: Changes that do not affect the meaning of the code (white-space, formatting, etc) +- **refactor**: A code change that neither fixes a bug nor adds a feature +- **perf**: A code change that improves performance +- **test**: Adding missing tests or correcting existing tests +- **build**: Changes that affect the build system or external dependencies +- **ci**: Changes to CI configuration files and scripts +- **chore**: Other changes that don't modify src or test files + +### Scope + +The scope should indicate the package or area affected (e.g., `library`, `yaml-reader`, `hidi`). + +### Examples + +``` +feat(library): add support for pattern properties +fix(yaml-reader): updates boolean serialization +docs(README): update installation instructions +ci(release): configure automated release workflow +``` + +### Breaking Changes + +If a commit introduces a breaking change, add `BREAKING CHANGE:` in the footer or append `!` after the type/scope: + +``` +feat(identity-emitter)!: change output format for models + +BREAKING CHANGE: The emitter now generates TypeScript interfaces instead of types +``` + + +## Updating the benchmark information + +The user might request you update the benchmark information. You might do it on your own if a previous change added new properties to models under **src/Microsoft.OpenApi/Models**. Always use a separate commit for this change. + +To do so, run the following script: + +```shell +cd performance/benchmark +dotnet run -c Release +``` + +Then commit the report files using a "chore" commit. \ No newline at end of file diff --git a/.github/dependabot.yml b/.github/dependabot.yml index d82ae27c9..87b987112 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -5,21 +5,23 @@ updates: directory: "/" open-pull-requests-limit: 10 schedule: - interval: "weekly" + interval: "daily" - package-ecosystem: "nuget" # location of package manifests directory: "/" open-pull-requests-limit: 10 schedule: interval: "daily" + groups: + MicrosoftExtensions: + patterns: + - "Microsoft.Extensions.*" - package-ecosystem: dotnet-sdk directory: / schedule: - interval: weekly - day: wednesday + interval: "daily" ignore: - dependency-name: '*' update-types: - version-update:semver-major - version-update:semver-minor -# Built with ❤ by [Pipeline Foundation](https://pipeline.foundation) 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/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..0d19e6ac4 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,54 @@ +# Pull Request + + + +## Description + + +## Type of Change + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Other (please describe): + +## Related Issue(s) + + +## Changes Made + +- +- +- + +## Testing + +- [ ] Unit tests added/updated +- [ ] Integration tests added/updated +- [ ] Manual testing performed +- [ ] All existing tests pass + +## Checklist + +- [ ] My code follows the code style of this project +- [ ] I have performed a self-review of my own code +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes + +## Versions applicability + +- [ ] My change applies to the version 1.X of the library, if so PR link: +- [ ] My change applies to the version 2.X of the library, if so PR link: +- [ ] My change applies to the version 3.X of the library, if so PR link: +- [ ] I have evaluated the applicability of my change against the other versions above. + +See [the contributing guidelines](https://github.com/microsoft/OpenAPI.NET/blob/main/CONTRIBUTING.md) for more information about how patches are applied across multiple versions. + +## Additional Notes + \ No newline at end of file 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/auto-merge-dependabot.yml b/.github/workflows/auto-merge-dependabot.yml index d454cd186..ba2243c97 100644 --- a/.github/workflows/auto-merge-dependabot.yml +++ b/.github/workflows/auto-merge-dependabot.yml @@ -19,7 +19,7 @@ jobs: steps: - name: Dependabot metadata id: metadata - uses: dependabot/fetch-metadata@v2.4.0 + uses: dependabot/fetch-metadata@v2.5.0 with: github-token: "${{ secrets.GITHUB_TOKEN }}" diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml index 9d55602b3..c13b4d179 100644 --- a/.github/workflows/ci-cd.yml +++ b/.github/workflows/ci-cd.yml @@ -20,7 +20,7 @@ jobs: - name: Checkout repository id: checkout_repo - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: token: ${{ secrets.GITHUB_TOKEN }} fetch-depth: 0 @@ -41,7 +41,7 @@ jobs: name: Validate Project for Trimming runs-on: windows-latest steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - name: Setup .NET uses: actions/setup-dotnet@v5 @@ -58,7 +58,7 @@ jobs: needs: [ci] steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@v6 - name: Setup .NET uses: actions/setup-dotnet@v5 @@ -76,7 +76,7 @@ jobs: working-directory: ./performance/benchmark - name: Publish benchmark results - uses: actions/upload-artifact@v5 + uses: actions/upload-artifact@v6 with: if-no-files-found: error name: benchmark-results diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index a69dbcb16..30c8acef4 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 * * *' @@ -20,7 +20,7 @@ jobs: steps: - name: Checkout repository id: checkout_repo - uses: actions/checkout@v5 + uses: actions/checkout@v6 - name: Setup .NET uses: actions/setup-dotnet@v5 diff --git a/.github/workflows/promote-shipped-apis.yml b/.github/workflows/promote-shipped-apis.yml new file mode 100644 index 000000000..aa611b7a0 --- /dev/null +++ b/.github/workflows/promote-shipped-apis.yml @@ -0,0 +1,113 @@ +name: Promote Shipped APIs + +on: + push: + branches: + - main + - support/v2 + workflow_dispatch: + +jobs: + promote-apis: + runs-on: ubuntu-latest + permissions: + contents: read + + steps: + - name: Generate GitHub App token + id: app-token + uses: actions/create-github-app-token@v2 + with: + app-id: ${{ vars.RELEASE_PLEASE_TOKEN_PROVIDER_APP_ID }} + private-key: ${{ secrets.RELEASE_PLEASE_TOKEN_PROVIDER_PEM }} + + - name: Checkout code + uses: actions/checkout@v6 + with: + fetch-depth: 0 + token: ${{ steps.app-token.outputs.token }} + + - name: Configure git + shell: pwsh + env: + GH_TOKEN: ${{ steps.app-token.outputs.token }} + run: | + git config --global user.name "github-actions[bot]" + git config --global user.email "github-actions[bot]@users.noreply.github.com" + git config --global url."https://$($env:GH_TOKEN)@github.com/".insteadOf "https://github.com/" + + - name: Check for existing PR + id: check_pr + shell: pwsh + env: + GH_TOKEN: ${{ steps.app-token.outputs.token }} + run: | + $branch = "${{ github.ref_name }}" + $prs = gh pr list --state open --head "promote-shipped-apis-$branch" --json number --jq '.[0].number' 2>$null + if ($prs) { + echo "pr_number=$prs" >> $env:GITHUB_OUTPUT + echo "pr_exists=true" >> $env:GITHUB_OUTPUT + Write-Host "Found existing PR: $prs" + } else { + echo "pr_exists=false" >> $env:GITHUB_OUTPUT + Write-Host "No existing PR found" + } + + - name: Checkout existing PR branch + if: steps.check_pr.outputs.pr_exists == 'true' + shell: pwsh + run: | + $branch = "${{ github.ref_name }}" + $prBranch = "promote-shipped-apis-$branch" + + git fetch origin + git checkout $prBranch + + - name: Merge trigger branch into PR branch + if: steps.check_pr.outputs.pr_exists == 'true' + shell: pwsh + run: | + $branch = "${{ github.ref_name }}" + git merge origin/$branch -m "Merge $branch into promote branch" + + - name: Run promote unshipped script + shell: pwsh + run: | + & .\scripts\promoteUnshipped.ps1 + + - name: Check for changes + id: check_changes + shell: pwsh + run: | + $changes = git diff --name-only -- "*Shipped.txt" + if ($changes) { + echo "has_changes=true" >> $env:GITHUB_OUTPUT + Write-Host "Changed files: $changes" + } else { + echo "has_changes=false" >> $env:GITHUB_OUTPUT + Write-Host "No changes detected" + } + + - name: Commit and push changes + if: steps.check_changes.outputs.has_changes == 'true' + shell: pwsh + run: | + git add *hipped.txt + git commit -m "chore: promote shipped APIs" + + $branch = "${{ github.ref_name }}" + $prBranch = "promote-shipped-apis-$branch" + git push -u origin HEAD:$prBranch + + - name: Create new PR + if: steps.check_pr.outputs.pr_exists == 'false' && steps.check_changes.outputs.has_changes == 'true' + shell: pwsh + env: + GH_TOKEN: ${{ steps.app-token.outputs.token }} + run: | + $branch = "${{ github.ref_name }}" + $prBranch = "promote-shipped-apis-$branch" + $title = "automatic promotion of shipped APIs for $branch" + + gh pr create --title "$title" --base "$branch" --head "$prBranch" --body "Automatically promotes unshipped APIs to shipped after running the promotion script." + diff --git a/.github/workflows/release-please-gha.yml b/.github/workflows/release-please-gha.yml index d24634b15..6e2c9825d 100644 --- a/.github/workflows/release-please-gha.yml +++ b/.github/workflows/release-please-gha.yml @@ -15,6 +15,8 @@ on: branches: - main - support/v1 + - support/v2 + workflow_dispatch: permissions: contents: read @@ -23,7 +25,31 @@ jobs: release: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 + + - name: Validate PublicAPI.Unshipped.txt files are empty + shell: pwsh + run: | + $unshippedFiles = Get-ChildItem 'src/ ' -Recurse -Filter *.Unshipped.txt | Select -ExpandProperty FullName + + $hasUnshippedAPIs = $false + + foreach ($file in $unshippedFiles) { + $content = Get-Content -Path $file -Raw + # Remove the #nullable enable line and any whitespace + $trimmedContent = $content -replace '^\s*#nullable enable\s*$', '' -replace '^\s+', '' + + if ($trimmedContent -ne '') { + Write-Error "❌ $file contains unshipped APIs. Please promote them to PublicAPI.Shipped.txt before releasing.`nContent:`n$content" + $hasUnshippedAPIs = $true + } + } + + if ($hasUnshippedAPIs) { + exit 1 + } + + Write-Output "✅ All PublicAPI.Unshipped.txt files are clean" - name: Generate GitHub App token id: app-token diff --git a/.github/workflows/sonarcloud.yml b/.github/workflows/sonarcloud.yml index 51f9b5986..7cd77844c 100644 --- a/.github/workflows/sonarcloud.yml +++ b/.github/workflows/sonarcloud.yml @@ -43,11 +43,11 @@ jobs: uses: actions/setup-dotnet@v5 with: dotnet-version: 8.0.x - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 with: fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis - name: Cache SonarCloud packages - uses: actions/cache@v4 + uses: actions/cache@v5 with: path: ~/.sonar/cache key: ${{ runner.os }}-sonar diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 3aedaf18b..0befe35d6 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.3.9" + ".": "3.3.1" } \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index f97968659..3d8605bbf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,155 @@ # Changelog -## [2.3.9](https://github.com/microsoft/OpenAPI.NET/compare/v2.3.8...v2.3.9) (2025-11-06) +## [3.3.1](https://github.com/microsoft/OpenAPI.NET/compare/v3.3.0...v3.3.1) (2026-01-22) + + +### Features + +* **models:** add shared Content interface ([#2695](https://github.com/microsoft/OpenAPI.NET/issues/2695)) ([338566f](https://github.com/microsoft/OpenAPI.NET/commit/338566fafce04ee1329f4ead61fe1e87e01144ad)) + + +### Bug Fixes + +* broken binary compatibility due to interface changes in previous version ([d96bba7](https://github.com/microsoft/OpenAPI.NET/commit/d96bba72c383cd5db2b7032530aee3b4d944ebc6)) + +## [3.3.0](https://github.com/microsoft/OpenAPI.NET/compare/v3.2.0...v3.3.0) (2026-01-21) + + +### Features + +* **models:** add shared Content interface ([9e13b25](https://github.com/microsoft/OpenAPI.NET/commit/9e13b2574e68387ecc01c453b571208c40124b46)) +* **models:** add shared Content interface ([#2695](https://github.com/microsoft/OpenAPI.NET/issues/2695)) ([9e13b25](https://github.com/microsoft/OpenAPI.NET/commit/9e13b2574e68387ecc01c453b571208c40124b46)) +* **models:** support mutualTLS security scheme ([a4efdfe](https://github.com/microsoft/OpenAPI.NET/commit/a4efdfe43ee310fba4bb643d9fd28ce92da32338)) + +## [3.2.0](https://github.com/microsoft/OpenAPI.NET/compare/v3.1.3...v3.2.0) (2026-01-19) + + +### Features + +* hidi validate command now logs warnings ([76a3c0f](https://github.com/microsoft/OpenAPI.NET/commit/76a3c0fe33a6c953263d9d91669b2f1bab562a79)) +* hidi validate command now logs warnings ([62e7d56](https://github.com/microsoft/OpenAPI.NET/commit/62e7d56ac0863875999240d68a2766d2cc2d594c)) + + +### Bug Fixes + +* discriminator property validation fails any/allOf cases when it shouldn't ([fb6cecc](https://github.com/microsoft/OpenAPI.NET/commit/fb6cecccafd5713bc1eb22e0cf07619cf495ebb5)) +* discriminator property validation fails any/allOf cases when it shouldn't ([a8fb81c](https://github.com/microsoft/OpenAPI.NET/commit/a8fb81cf9524a3f2f721aa808db244434e1cd177)) + +## [3.1.3](https://github.com/microsoft/OpenAPI.NET/compare/v3.1.2...v3.1.3) (2026-01-16) + + +### Bug Fixes + +* Support custom tag ordering ([008576c](https://github.com/microsoft/OpenAPI.NET/commit/008576c31f8dcecf59363c9c2f85d691601faa73)) +* Support custom tag ordering ([7610d07](https://github.com/microsoft/OpenAPI.NET/commit/7610d07bd11a99a4ce1cc31338d180dbd764d952)) + +## [3.1.2](https://github.com/microsoft/OpenAPI.NET/compare/v3.1.1...v3.1.2) (2026-01-06) + +### Bug Fixes + +* correct error pointer when extension parser throws OpenApiException ([43c75a9](https://github.com/microsoft/OpenAPI.NET/commit/43c75a90746344fcc975611100e995fe4045edf0)) +* wrap extension parser calls in try-catch to ensure correct error pointers ([50b44aa](https://github.com/microsoft/OpenAPI.NET/commit/50b44aad12d8fa86a46f7f6d62896a7b1c344d2e)) + +## [3.1.1](https://github.com/microsoft/OpenAPI.NET/compare/v3.1.0...v3.1.1) (2025-12-18) + + +### Bug Fixes + +* **schema:** always serialize `additionalProperties: false` ([6651c36](https://github.com/microsoft/OpenAPI.NET/commit/6651c36ff341329c053776d65b36b1b7fa9dd3ea)) +* **schema:** always serialize `additionalProperties: false` ([e36fc95](https://github.com/microsoft/OpenAPI.NET/commit/e36fc9565bce42916eb7bf64d1f74d491dd1f407)) + +## [3.1.0](https://github.com/microsoft/OpenAPI.NET/compare/v3.0.3...v3.1.0) (2025-12-17) + +### Features + +* Add `type: "null"` downcasting when in oneOf and anyOf for OpenAPI v3 ([782cf8d](https://github.com/microsoft/OpenAPI.NET/commit/782cf8d1ff8166e3c7be706e08dabf168b9616a4)) + +## [3.0.3](https://github.com/microsoft/OpenAPI.NET/compare/v3.0.2...v3.0.3) (2025-12-16) + + +* load JSON documents that are preceded by multiple whitespace ([6461bac](https://github.com/microsoft/OpenAPI.NET/commit/6461bac01c4176424210e9ac249698f665a514a6)) +* non-seekable json streams would fail to load as a document ([2436d73](https://github.com/microsoft/OpenAPI.NET/commit/2436d7382bfbf8b9ba501d88f682e952bdf27146)) +* reading streams in an asp.net context would cause async exceptions ([f9e5248](https://github.com/microsoft/OpenAPI.NET/commit/f9e524859722476b3111cb6006f77208c2d1f526)) +## [3.0.2](https://github.com/microsoft/OpenAPI.NET/compare/v3.0.1...v3.0.2) (2025-12-08) + +### Bug Fixes + +* additional properties serialization should not emit a schema in v2 ([946cba9](https://github.com/microsoft/OpenAPI.NET/commit/946cba992a2733a60182453e38722b4ed789b729)) +* additional properties serialization should not emit booleans in v3.1+ ([946cba9](https://github.com/microsoft/OpenAPI.NET/commit/946cba992a2733a60182453e38722b4ed789b729)) + +## [3.0.1](https://github.com/microsoft/OpenAPI.NET/compare/v3.0.0...v3.0.1) (2025-11-17) + +### Bug Fixes + +* empty strings should be quoted in yaml ([8d215f9](https://github.com/microsoft/OpenAPI.NET/commit/8d215f9ea8a780b1e2e8dd6cefb8d470cc35682d)) +* empty strings should be quoted in yaml ([0ca10db](https://github.com/microsoft/OpenAPI.NET/commit/0ca10db3bb9ffa937dd35862068926f3586d6991)) + +## [3.0.0](https://github.com/microsoft/OpenAPI.NET/compare/v2.3.9...v3.0.0) (2025-11-11) + +### ⚠ BREAKING CHANGES + +* adds support for OpenAPI 3.2.0 + +> Note: Please refer to the [upgrade guide](https://github.com/microsoft/OpenAPI.NET/blob/main/docs/upgrade-guide-3.md) for a detailed description of the breaking changes. + +> Note: ASP.net users should remain on version 1.X for ASP.net < 10, and version 2.X for ASP.net 10, this new major version will be implemented in a future version of ASP.net, [more information](https://github.com/microsoft/OpenAPI.NET/blob/main/CONTRIBUTING.md#branches-and-support-policy) + +### Features + +* adds support for OpenAPI 3.2.0 ([765a8dd](https://github.com/microsoft/OpenAPI.NET/commit/765a8dd4d6efd1a31b6a76d282ccffa5877a845a)) + +## [2.4.3](https://github.com/microsoft/OpenAPI.NET/compare/v2.4.2...v2.4.3) (2026-01-16) + +## Bug Fixes + +* Support custom tag ordering ([008576c](https://github.com/microsoft/OpenAPI.NET/commit/008576c31f8dcecf59363c9c2f85d691601faa73)) +* Support custom tag ordering ([7610d07](https://github.com/microsoft/OpenAPI.NET/commit/7610d07bd11a99a4ce1cc31338d180dbd764d952)) + +## [2.4.2](https://github.com/microsoft/OpenAPI.NET/compare/v2.4.1...v2.4.2) (2025-12-22) + + +### Bug Fixes + +* wrap extension parser calls in try-catch to ensure correct error pointers ([63cf4a3](https://github.com/microsoft/OpenAPI.NET/commit/63cf4a3029fe2d285a6fe2724e30ffcf3bdd2f9f)) +* wrap extension parser calls in try-catch to ensure correct error pointers ([458cabe](https://github.com/microsoft/OpenAPI.NET/commit/458cabe6cd0fbdb192dbd17f2d6ab3b8162d1166)) + +## [2.4.1](https://github.com/microsoft/OpenAPI.NET/compare/v2.4.0...v2.4.1) (2025-12-18) + +### Bug Fixes + +* **schema:** always serialize `additionalProperties: false` ([6651c36](https://github.com/microsoft/OpenAPI.NET/commit/6651c36ff341329c053776d65b36b1b7fa9dd3ea)) +* **schema:** always serialize `additionalProperties: false` ([e36fc95](https://github.com/microsoft/OpenAPI.NET/commit/e36fc9565bce42916eb7bf64d1f74d491dd1f407)) + +## [2.4.0](https://github.com/microsoft/OpenAPI.NET/compare/v2.3.12...v2.4.0) (2025-12-17) + +### Features + +* Add `type: "null"` downcasting when in oneOf and anyOf for OpenAPI v3 ([782cf8d](https://github.com/microsoft/OpenAPI.NET/commit/782cf8d1ff8166e3c7be706e08dabf168b9616a4)) + +## [2.3.12](https://github.com/microsoft/OpenAPI.NET/compare/v2.3.11...v2.3.12) (2025-12-15) + +### Bug Fixes + +* load JSON documents that are preceded by multiple whitespace ([640e59a](https://github.com/microsoft/OpenAPI.NET/commit/640e59a143a2a6d3b79c9f6a97a6029593d7dd8f)) +* non-seekable json streams would fail to load as a document ([76b0159](https://github.com/microsoft/OpenAPI.NET/commit/76b0159d12790ab00310ff107e37396ecdf13336)) +* non-seekable json streams would fail to load as a document ([2436d73](https://github.com/microsoft/OpenAPI.NET/commit/2436d7382bfbf8b9ba501d88f682e952bdf27146)) +* reading streams in an asp.net context would cause async exceptions ([f9e5248](https://github.com/microsoft/OpenAPI.NET/commit/f9e524859722476b3111cb6006f77208c2d1f526)) + +## [2.3.11](https://github.com/microsoft/OpenAPI.NET/compare/v2.3.10...v2.3.11) (2025-12-08) + +### Bug Fixes + +* additional properties serialization should not emit a schema in v2 ([946cba9](https://github.com/microsoft/OpenAPI.NET/commit/946cba992a2733a60182453e38722b4ed789b729)) +* additional properties serialization should not emit a schema in v2 fix: additional properties serialization should not emit booleans in v3.1+ ([275dd9d](https://github.com/microsoft/OpenAPI.NET/commit/275dd9d7525b1f490eccaf1e6e60829ae51bdf5d)) +* additional properties serialization should not emit booleans in v3.1+ ([946cba9](https://github.com/microsoft/OpenAPI.NET/commit/946cba992a2733a60182453e38722b4ed789b729)) + +## [2.3.10](https://github.com/microsoft/OpenAPI.NET/compare/v2.3.9...v2.3.10) (2025-11-17) + +* empty strings should be quoted in yaml ([e919b33](https://github.com/microsoft/OpenAPI.NET/commit/e919b33e9d09159217066248483ef4c767865c82)) +* empty strings should be quoted in yaml ([0ca10db](https://github.com/microsoft/OpenAPI.NET/commit/0ca10db3bb9ffa937dd35862068926f3586d6991)) + +## [2.3.9](https://github.com/microsoft/OpenAPI.NET/compare/v2.3.8...v2.3.9) (2025-11-06) ### Bug Fixes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a08924c7b..7719a3839 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,7 @@ OpenAPI.net is a mono-repo containing source code for the following packages: | Library | NuGet Release | |----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Microsoft.OpenAPI](./src/Microsoft.OpenAPI/README.md) | [![NuGet Version](https://img.shields.io/nuget/vpre/Microsoft.OpenAPI?label=Latest&logo=nuget)](https://www.nuget.org/packages/Microsoft.OpenAPI/) | -| [Microsoft.OpenAPI.Readers](./src/Microsoft.OpenAPI.Readers/README.md) | [![NuGet Version](https://img.shields.io/nuget/vpre/Microsoft.OpenAPI.Readers?label=Latest&logo=nuget)](https://www.nuget.org/packages/Microsoft.OpenAPI.Readers/) | +| [Microsoft.OpenAPI.YamlReader](./src/Microsoft.OpenApi.YamlReader/README.md) | [![NuGet Version](https://img.shields.io/nuget/vpre/Microsoft.OpenAPI.YamlReader?label=Latest&logo=nuget)](https://www.nuget.org/packages/Microsoft.OpenAPI.YamlReader/) | | [Microsoft.OpenAPI.Hidi](./src/Microsoft.OpenAPI.Hidi/README.md) | [![NuGet Version](https://img.shields.io/nuget/vpre/Microsoft.OpenAPI.Hidi?label=Latest&logo=nuget)](https://www.nuget.org/packages/Microsoft.OpenAPI.Hidi/) | OpenAPI.net is open to contributions. There are a couple of different recommended paths to get contributions into the released version of this library. @@ -20,7 +20,32 @@ The best way to get started with a contribution is to start a dialog with the ow ## Submit pull requests for bug fixes and features -Feel free to submit a pull request with a linked issue against the __main__ branch. The main branch will be updated frequently. +Feel free to submit a pull request with a linked issue. + +### Branches and support policy + +Because one major consumer of these libraries is ASP.net, the support policy of this repository is aligned with [dotnet support policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core#lifecycle). + +The following table outlines the mapping between package major versions, dotnet versions, and which contributions are accepted. As a consumer, make sure the version of this library your application is using is aligned with the version of ASP.net described in the table below. + +| Major version | Branch | Supported [AspNetCore OpenAPI versions](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) | Supported [Swashbuckle.AspNetCore version](https://www.nuget.org/packages/Swashbuckle.AspNetCore/) | Supported OpenAPI versions | Changes provided by Microsoft | Accepted contributions | End of support date | +| ------------- | ---------- | -------------------------- | ---------- | -------------------------- | ------------------------------------------- | ------------------------------------------- | --------------- | +| 1.X | support/v1 | < 10 | < 10 | 2.0, 3.0 | security fixes | security and bugfixes | .NET 9 (Nov 2026) | +| 2.X | support/v2 | = 10 ¹ | = 10 ³ | 2.0, 3.0, 3.1 | security and bugfixes | security and bugfixes | .NET 10 (Nov 2028) ¹ | +| 3.X ² | main | not available | not available | 2.0, 3.0, 3.1, 3.2 | security, bugfixes and feature improvements | security, bugfixes and feature improvements | TBD | + +> Notes: +> +> 1. This assumes that AspNetCore OpenAPI version 11 and above will adopt version 3 or above of this library, otherwise, it'd expand the support date for version 2 of this library. +> 2. This will be conditioned by new releases of OpenAPI, this library, ASP.NET and AspNetCore OpenAPI's adoption of new versions of this library. +> 3. This assumes that Swashbuckle.AspNetCore version 11 and above will adopt version 3 or above of this library. + +### Multi-versions requirement for contributions + +When contributing to the library, start by making a contribution to the main branch first, or the uppermost version it applies to. During the review process you'll be asked to demonstrate your contribution cannot apply to prior versions or to port your contribution to the branches for prior versions before the initial pull request can get merged. + +This approach helps maintain a similar behavior across all versions under active support. + ## Commit message format To support our automated release process, pull requests are required to follow the [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) @@ -49,4 +74,53 @@ The recommended commit types used are: - __ci__ for CI configuration file changes e.g. updating a pipeline - __chore__ for miscallaneous non-sdk changesin the repo e.g. removing an unused file -Adding an exclamation mark after the commit type (`feat!`) or footer with the prefix __BREAKING CHANGE:__ will cause an increment of the _major_ version. \ No newline at end of file +Adding an exclamation mark after the commit type (`feat!`) or footer with the prefix __BREAKING CHANGE:__ will cause an increment of the _major_ version. + +## Updates to public API surface + +Because we need to maintain a compatible public API surface within a major version, this project is using the public API analyzers to ensure no prior public API is changed/removed inadvertently. + +This means that: + +- All entries in an __Unshipped__ document need to be moved to the __Shipped__ document before any public release. +- All new APIs being added need to be __Unshipped__ document before the pull request can be merged, otherwise build will fail with a message like the example below. + +```txt +Error: /home/runner/work/OpenAPI.NET/OpenAPI.NET/src/Microsoft.OpenApi/Models/OpenApiSecurityScheme.cs(39,46): error RS0016: Symbol 'OAuth2MetadataUrl.set' is not part of the declared public API (https://github.com/dotnet/roslyn-analyzers/blob/main/src/PublicApiAnalyzers/PublicApiAnalyzers.Help.md) [/home/runner/work/OpenAPI.NET/OpenAPI.NET/src/Microsoft.OpenApi/Microsoft.OpenApi.csproj::TargetFramework=net8.0] +``` + +### Update the unshipped document + +To update the unshipped document, simply run the following commands + +```shell +# add the missing public api entries +dotnet format --diagnostics RS0016 +# discard changes to cs files to avoid creating conflicts +git checkout *.cs +``` + +### Move items from unshipped to unshipped document + +```pwsh +. ./scripts/promoteUnshipped.ps1 +``` + +> Note: the promotion of APIs is automated through the dedicated workflow and should result in pull requests being automatically opened. + +## Updating the benchmark information + +To ensure performance of the library does not degrade over time, we have continuous benchmarks running. You might see the continuous integration failing if your pull request changed any model under __src/Microsoft.OpenApi/Models__. + +```txt +Benchmark result for EmptyApiSchema does not match the existing benchmark result (original!=new). Allocated bytes differ: 408 != 416 +``` + +To update the benchmarks, run the following script: + +```shell +cd performance/benchmark +dotnet run -c Release +``` + +Then commit the report files using a "chore" commit. diff --git a/Directory.Build.props b/Directory.Build.props index 8ef14df8e..97bc7f633 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -12,13 +12,13 @@ https://github.com/Microsoft/OpenAPI.NET © Microsoft Corporation. All rights reserved. OpenAPI .NET - 2.3.9 + 3.3.1 true - + \ No newline at end of file diff --git a/README.md b/README.md index 99d0a1aee..6a7f787f8 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,8 @@ Project Objectives: - Install core Nuget package [**Microsoft.OpenApi**](https://www.nuget.org/packages/Microsoft.OpenApi) - Install Yaml Reader Nuget package [**Microsoft.OpenApi.YamlReader**](https://www.nuget.org/packages/Microsoft.OpenApi.YamlReader) -> Note: we just released a new major version of the library, which brings support for OpenAPI 3.1! -> You can read more about the changes of this upcoming version [in the upgrade guide](./docs/upgrade-guide-2.md). +> Note: we just released a new major version of the library, which brings support for OpenAPI 3.2! +> You can read more about the changes of this upcoming version [in the upgrade guide](./docs/upgrade-guide-3.md). # Processors The OpenAPI.NET project holds the base object model for representing OpenAPI documents as .NET objects. Some developers have found the need to write processors that convert other data formats into this OpenAPI.NET object model. We'd like to curate that list of processors in this section of the readme. diff --git a/build.cmd b/build.cmd index 43cc95956..07daf7b6c 100644 --- a/build.cmd +++ b/build.cmd @@ -6,9 +6,9 @@ dotnet msbuild %PROJ% /t:restore /p:Configuration=Release dotnet msbuild %PROJ% /t:build /p:Configuration=Release dotnet msbuild %PROJ% /t:pack /p:Configuration=Release;PackageOutputPath=%~dp0artifacts -Echo Building Microsoft.OpenApi.Readers +Echo Building Microsoft.OpenApi.YamlReader -SET PROJ=%~dp0src\Microsoft.OpenApi.Readers\Microsoft.OpenApi.Readers.csproj +SET PROJ=%~dp0src\Microsoft.OpenApi.YamlReader\Microsoft.OpenApi.YamlReader.csproj dotnet msbuild %PROJ% /t:restore /p:Configuration=Release dotnet msbuild %PROJ% /t:build /p:Configuration=Release dotnet msbuild %PROJ% /t:pack /p:Configuration=Release;PackageOutputPath=%~dp0artifacts diff --git a/build.sh b/build.sh index e716aa272..0de30b6df 100755 --- a/build.sh +++ b/build.sh @@ -7,9 +7,9 @@ dotnet msbuild "$PROJ" /t:restore /p:Configuration=Release dotnet msbuild "$PROJ" /t:build /p:Configuration=Release dotnet msbuild "$PROJ" /t:pack "/p:Configuration=Release;PackageOutputPath=$(dirname "$0")/artifacts" -echo "Building Microsoft.OpenApi.Readers" +echo "Building Microsoft.OpenApi.YamlReader" -PROJ="$(dirname "$0")/src/Microsoft.OpenApi.Readers/Microsoft.OpenApi.Readers.csproj" +PROJ="$(dirname "$0")/src/Microsoft.OpenApi.YamlReader/Microsoft.OpenApi.YamlReader.csproj" dotnet msbuild "$PROJ" /t:restore /p:Configuration=Release dotnet msbuild "$PROJ" /t:build /p:Configuration=Release dotnet msbuild "$PROJ" /t:pack "/p:Configuration=Release;PackageOutputPath=$(dirname "$0")/artifacts" diff --git a/docs/upgrade-guide-2.md b/docs/upgrade-guide-2.md index 5546e4896..752b60c95 100644 --- a/docs/upgrade-guide-2.md +++ b/docs/upgrade-guide-2.md @@ -12,7 +12,15 @@ 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. > [!WARNING] -> If you are using this library with ASP.NET Core version `< 10.0` then you must remain on version `1.x` as it's not compatible. +> 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](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) `< 10.0` then you must remain on version `1.x` as it's not compatible with version 2 or above of this library. + +If you are using this library with [Swashbuckle.AspNetCore version](https://www.nuget.org/packages/Swashbuckle.AspNetCore/) `< 10.0` then you must remain on version `1.x` as it's not compatible with version 2 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](https://github.com/microsoft/OpenAPI.NET/blob/main/CONTRIBUTING.md#branches-and-support-policy). ## The biggest update ever @@ -24,7 +32,7 @@ One of the key features of OpenAPI.NET is its performance. This version makes it In v1, instances of `$ref` were resolved in a second pass of the document to ensure the target of the reference has been parsed before attempting to resolve it. In v2, reference targets are lazily resolved when reference objects are accessed. This improves load time performance for documents that make heavy use of references. -[How does this change the behavior of external references?] +Because references are lazily loaded and depend on the workspace context, loading a document with unresolved references (internal or external) does not lead to an exception being thrown anymore. Instead warnings are logged in the diagnostics object. This gives you an opportunity to load additional documents in the workspace if needed, [more information](#component-registration-in-a-documents-workspace). ### Results diff --git a/docs/upgrade-guide-3.md b/docs/upgrade-guide-3.md new file mode 100644 index 000000000..49e467d24 --- /dev/null +++ b/docs/upgrade-guide-3.md @@ -0,0 +1,398 @@ +# 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](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) `< 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](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) `= 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](https://www.nuget.org/packages/Swashbuckle.AspNetCore/) `< 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](https://www.nuget.org/packages/Swashbuckle.AspNetCore/) `= 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](https://github.com/microsoft/OpenAPI.NET/blob/main/CONTRIBUTING.md#branches-and-support-policy). + +## 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/global.json b/global.json index 4c2f00caf..459fe3e6e 100644 --- a/global.json +++ b/global.json @@ -1,5 +1,5 @@ { "sdk": { - "version": "8.0.415" + "version": "8.0.418" } } \ No newline at end of file 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 3f182cfb6..8f25e090e 100644 --- a/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report-github.md +++ b/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report-github.md @@ -1,10 +1,10 @@ ``` -BenchmarkDotNet v0.15.4, Windows 11 (10.0.26200.6899) +BenchmarkDotNet v0.15.8, Windows 11 (10.0.26200.7781/25H2/2025Update/HudsonValley2) 11th Gen Intel Core i7-1185G7 3.00GHz, 1 CPU, 8 logical and 4 physical cores -.NET SDK 8.0.415 - [Host] : .NET 8.0.21 (8.0.21, 8.0.2125.47513), X64 RyuJIT x86-64-v4 - ShortRun : .NET 8.0.21 (8.0.21, 8.0.2125.47513), X64 RyuJIT x86-64-v4 +.NET SDK 8.0.418 + [Host] : .NET 8.0.24 (8.0.24, 8.0.2426.7010), X64 RyuJIT x86-64-v4 + ShortRun : .NET 8.0.24 (8.0.24, 8.0.2426.7010), X64 RyuJIT x86-64-v4 Job=ShortRun IterationCount=3 LaunchCount=1 WarmupCount=3 @@ -12,7 +12,7 @@ WarmupCount=3 ``` | Method | Mean | Error | StdDev | Gen0 | Gen1 | Gen2 | Allocated | |------------- |-------------:|--------------:|-------------:|-----------:|-----------:|----------:|-------------:| -| PetStoreYaml | 407.7 μs | 134.55 μs | 7.38 μs | 58.5938 | 7.8125 | - | 360.8 KB | -| PetStoreJson | 166.3 μs | 23.12 μs | 1.27 μs | 36.1328 | 6.8359 | - | 222.95 KB | -| GHESYaml | 896,578.2 μs | 138,441.39 μs | 7,588.44 μs | 60000.0000 | 23000.0000 | 4000.0000 | 345015.7 KB | -| GHESJson | 432,991.2 μs | 243,041.11 μs | 13,321.90 μs | 33000.0000 | 12000.0000 | 2000.0000 | 206538.29 KB | +| PetStoreYaml | 405.2 μs | 162.42 μs | 8.90 μs | 58.5938 | 11.7188 | - | 361.39 KB | +| PetStoreJson | 173.0 μs | 23.21 μs | 1.27 μs | 36.1328 | 6.8359 | - | 223.53 KB | +| GHESYaml | 951,103.8 μs | 629,262.79 μs | 34,492.02 μs | 60000.0000 | 22000.0000 | 4000.0000 | 345343.16 KB | +| GHESJson | 435,425.1 μs | 88,170.37 μs | 4,832.92 μs | 33000.0000 | 12000.0000 | 2000.0000 | 206865.71 KB | diff --git a/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report.csv b/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report.csv index 36925dad9..c009438ba 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,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,407.7 μs,134.55 μs,7.38 μs,58.5938,7.8125,0.0000,360.8 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,166.3 μs,23.12 μs,1.27 μs,36.1328,6.8359,0.0000,222.95 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,"896,578.2 μs","138,441.39 μs","7,588.44 μs",60000.0000,23000.0000,4000.0000,345015.7 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,"432,991.2 μs","243,041.11 μs","13,321.90 μs",33000.0000,12000.0000,2000.0000,206538.29 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,405.2 μs,162.42 μs,8.90 μs,58.5938,11.7188,0.0000,361.39 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,173.0 μs,23.21 μs,1.27 μs,36.1328,6.8359,0.0000,223.53 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,"951,103.8 μs","629,262.79 μs","34,492.02 μs",60000.0000,22000.0000,4000.0000,345343.16 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,"435,425.1 μs","88,170.37 μs","4,832.92 μs",33000.0000,12000.0000,2000.0000,206865.71 KB diff --git a/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report.html b/performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report.html index 39bab3925..0a83de262 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-20251023-154034 +performance.Descriptions-20260219-140039