Releases: microsoft/OpenAPI.NET
2.0.0-preview4
Changes:
- #2028: dev
- #2027: chore: bumps preview version
- #2026: fix: specifies encoding for net fx
- #2024: feat: adds deconstructor to read result
- #2023: fix: enum description number values
- #2025: chore(deps): bump Verify.Xunit from 28.6.1 to 28.7.0
- #2021: fix/ci tag value to main
- #2019: fix: reverts to a regular variable for the tag value
- #2015: release of preview 3
- #2017: fix/ci hidi gh upload to main
See More
- #2016: fix/ci hidi gh upload
- #1975: Refactor readers to reduce surface area
- #2014: chore/v1 sync
- #2008: ci: fixes hidi gh release
- #2005: ci: updates main with the latest ci changes
- #2003: chore(deps): bump Verify.Xunit from 28.2.0 to 28.6.1
- #2001: ci/align branches
- #1999: chore: fixes extraneous master references
- #2000: fix: sets hidi version to a preview
- #1997: chore/linting
- #1982: Add support for handling unrecognized keywords
- #1981: Rename Read Result properties
- #1996: chore: adds baywet to code owners
- #1993: chore(deps): bump Verify.Xunit from 28.5.0 to 28.6.0
- #1994: chore(deps): bump PublicApiGenerator from 11.2.0 to 11.3.0
- #1939: Fix tags serialization bug
- #1992: chore(deps): bump xunit.runner.visualstudio from 2.8.2 to 3.0.0
- #1990: chore(deps): bump Verify.Xunit from 28.4.0 to 28.5.0
- #1988: Bump preview versions
- #1984: chore(deps): bump PublicApiGenerator from 11.1.0 to 11.2.0
- #1986: chore(deps): bump Microsoft.OData.Edm from 8.2.2 to 8.2.3
- #1979: chore(deps): bump FluentAssertions from 6.12.2 to 7.0.0
- #1978: Fix: Adds missing security metadata to the pipeline
- #1977: chore(deps): bump docker/build-push-action from 6.9.0 to 6.10.0
- #1976: chore(deps): bump Verify.Xunit from 28.3.2 to 28.4.0
- #1955: Fix: Empty paths object is now failing for version 3.0.0
- #1943: Add support for JSON schema
const
keyword in OpenApiSchema - #1956: Fix: Workbench fails because of a missing format parameter
- #1942: Use range for STJ reference and suppress warnings
- #1945: chore(deps): bump Microsoft.NET.Test.Sdk from 17.11.1 to 17.12.0
- #1944: chore(deps): bump Microsoft.OData.Edm from 8.2.1 to 8.2.2
- #1941: chore(deps): bump Verify.Xunit from 28.3.1 to 28.3.2
- #1938: Fix link to OpenAPI specification
- #1936: chore(deps): bump Verify.Xunit from 28.2.1 to 28.3.1
- #1932: chore(deps): bump Microsoft.Extensions.Logging, Microsoft.Extensions.Logging.Abstractions, Microsoft.Extensions.Logging.Console and System.Text.Json
- #1931: chore: removes newtonsoft dependency all together
- #1927: chore(deps): bump Microsoft.OData.Edm from 8.2.0 to 8.2.1
- #1926: chore(deps): bump Microsoft.Extensions.Logging and Microsoft.Extensions.Logging.Abstractions
- #1928: chore(deps): bump Microsoft.VisualStudio.Threading.Analyzers from 17.11.20 to 17.12.19
- #1925: chore(deps): bump Verify.Xunit from 28.2.0 to 28.2.1
- #1915: fix: multiple performance fixes for type serialization feat: adds to identifier mapping to non nullable enum
- #1919: chore(deps): bump Microsoft.Extensions.Logging.Abstractions from 8.0.2 to 9.0.0
- #1921: chore(deps): bump System.Formats.Asn1 and Microsoft.Windows.Compatibility
- #1920: chore(deps): bump System.Text.Json from 8.0.5 to 9.0.0
- #1914: Release hidi and libs
- #1913: Bump up libs and hidi versions
- #1894: feature/3.1.1
- #1823: feature/3 0 4
- #1912: chore(deps): bump Verify.Xunit from 28.0.0 to 28.2.0
- #1909: chore(deps): bump Microsoft.OData.Edm from 8.1.0 to 8.2.0
- #1910: chore(deps): bump FluentAssertions from 6.12.1 to 6.12.2
- #1908: Release hidi
- #1907: Bump hidi version
- #1906: V2-preview1 release
- #1904: V2.0-preview1 release
- #1903: Sync latest vnext changes
- #1897: Define JSON schema's Type property as a flaggable enum to allow storing multiple values
- #1900: chore(deps): bump Verify.Xunit from 27.1.0 to 28.0.0
- #1888: Remove DataTypeMismatch validation rule from the default ruleset
- #1899: OpenApiSchema refactor to remove recursive keywords
- #1898: Release Hidi
- #1896: Bump up hidi and conversion lib versions
This list of changes was auto generated.
2.0.0-preview3
Changes:
- #2021: fix/ci tag value to main
- #2015: release of preview 3
- #2017: fix/ci hidi gh upload to main
- #2016: fix/ci hidi gh upload
- #1975: Refactor readers to reduce surface area
- #2014: chore/v1 sync
- #2008: ci: fixes hidi gh release
- #2005: ci: updates main with the latest ci changes
- #2003: chore(deps): bump Verify.Xunit from 28.2.0 to 28.6.1
- #2001: ci/align branches
See More
- #1999: chore: fixes extraneous master references
- #2000: fix: sets hidi version to a preview
- #1997: chore/linting
- #1982: Add support for handling unrecognized keywords
- #1981: Rename Read Result properties
- #1996: chore: adds baywet to code owners
- #1993: chore(deps): bump Verify.Xunit from 28.5.0 to 28.6.0
- #1994: chore(deps): bump PublicApiGenerator from 11.2.0 to 11.3.0
- #1939: Fix tags serialization bug
- #1992: chore(deps): bump xunit.runner.visualstudio from 2.8.2 to 3.0.0
- #1990: chore(deps): bump Verify.Xunit from 28.4.0 to 28.5.0
- #1988: Bump preview versions
- #1984: chore(deps): bump PublicApiGenerator from 11.1.0 to 11.2.0
- #1986: chore(deps): bump Microsoft.OData.Edm from 8.2.2 to 8.2.3
- #1979: chore(deps): bump FluentAssertions from 6.12.2 to 7.0.0
- #1978: Fix: Adds missing security metadata to the pipeline
- #1977: chore(deps): bump docker/build-push-action from 6.9.0 to 6.10.0
- #1976: chore(deps): bump Verify.Xunit from 28.3.2 to 28.4.0
- #1955: Fix: Empty paths object is now failing for version 3.0.0
- #1943: Add support for JSON schema
const
keyword in OpenApiSchema - #1956: Fix: Workbench fails because of a missing format parameter
- #1942: Use range for STJ reference and suppress warnings
- #1945: chore(deps): bump Microsoft.NET.Test.Sdk from 17.11.1 to 17.12.0
- #1944: chore(deps): bump Microsoft.OData.Edm from 8.2.1 to 8.2.2
- #1941: chore(deps): bump Verify.Xunit from 28.3.1 to 28.3.2
- #1938: Fix link to OpenAPI specification
- #1936: chore(deps): bump Verify.Xunit from 28.2.1 to 28.3.1
- #1932: chore(deps): bump Microsoft.Extensions.Logging, Microsoft.Extensions.Logging.Abstractions, Microsoft.Extensions.Logging.Console and System.Text.Json
- #1931: chore: removes newtonsoft dependency all together
- #1927: chore(deps): bump Microsoft.OData.Edm from 8.2.0 to 8.2.1
- #1926: chore(deps): bump Microsoft.Extensions.Logging and Microsoft.Extensions.Logging.Abstractions
- #1928: chore(deps): bump Microsoft.VisualStudio.Threading.Analyzers from 17.11.20 to 17.12.19
- #1925: chore(deps): bump Verify.Xunit from 28.2.0 to 28.2.1
- #1915: fix: multiple performance fixes for type serialization feat: adds to identifier mapping to non nullable enum
- #1919: chore(deps): bump Microsoft.Extensions.Logging.Abstractions from 8.0.2 to 9.0.0
- #1921: chore(deps): bump System.Formats.Asn1 and Microsoft.Windows.Compatibility
- #1920: chore(deps): bump System.Text.Json from 8.0.5 to 9.0.0
- #1914: Release hidi and libs
- #1913: Bump up libs and hidi versions
- #1894: feature/3.1.1
- #1823: feature/3 0 4
- #1912: chore(deps): bump Verify.Xunit from 28.0.0 to 28.2.0
- #1909: chore(deps): bump Microsoft.OData.Edm from 8.1.0 to 8.2.0
- #1910: chore(deps): bump FluentAssertions from 6.12.1 to 6.12.2
- #1908: Release hidi
- #1907: Bump hidi version
- #1906: V2-preview1 release
- #1904: V2.0-preview1 release
- #1903: Sync latest vnext changes
- #1897: Define JSON schema's Type property as a flaggable enum to allow storing multiple values
- #1900: chore(deps): bump Verify.Xunit from 27.1.0 to 28.0.0
- #1888: Remove DataTypeMismatch validation rule from the default ruleset
- #1899: OpenApiSchema refactor to remove recursive keywords
- #1898: Release Hidi
- #1896: Bump up hidi and conversion lib versions
- #1890: Update workbench tool to parse 3.1 and YAML docs
- #1895: chore(deps): bump Verify.Xunit from 27.0.1 to 27.1.0
- #1892: docs: fixes doc comments to align with changes made in #1883
- #1883: fix: emits number for integer formats
- #1893: merge/vnext to release2
This list of changes was auto generated.
1.6.23
Changes:
- #2020: fix: reverts to a regular variable for the tag value
- #2018: fix/ci hidi gh upload to v1
- #2013: chore: bumps version for releasing
- #2012: chore/hidi maintenance
- #2011: feat: bumps v3 patch version to 3.0.4
- #2010: ci: fixes hidi gh release
- #2007: security: bumps STJ version to fix security vulnerabilities
This list of changes was auto generated.
2.0.0-preview2
Changes:
- #1914: Release hidi and libs
- #1913: Bump up libs and hidi versions
- #1894: feature/3.1.1
- #1823: feature/3 0 4
- #1912: chore(deps): bump Verify.Xunit from 28.0.0 to 28.2.0
- #1909: chore(deps): bump Microsoft.OData.Edm from 8.1.0 to 8.2.0
- #1910: chore(deps): bump FluentAssertions from 6.12.1 to 6.12.2
- #1908: Release hidi
- #1907: Bump hidi version
- #1906: V2-preview1 release
See More
- #1904: V2.0-preview1 release
- #1903: Sync latest vnext changes
- #1897: Define JSON schema's Type property as a flaggable enum to allow storing multiple values
- #1900: chore(deps): bump Verify.Xunit from 27.1.0 to 28.0.0
- #1888: Remove DataTypeMismatch validation rule from the default ruleset
- #1899: OpenApiSchema refactor to remove recursive keywords
- #1898: Release Hidi
- #1896: Bump up hidi and conversion lib versions
- #1890: Update workbench tool to parse 3.1 and YAML docs
- #1895: chore(deps): bump Verify.Xunit from 27.0.1 to 27.1.0
- #1892: docs: fixes doc comments to align with changes made in #1883
- #1883: fix: emits number for integer formats
- #1893: merge/vnext to release2
- #1886: use nameof for CallerArgumentExpression
- #1887: Simplify null/empty string checks
- #1885: Release Hidi lib.
- #1884: Bump, Release Hidi
- #1881: chore(deps): bump Microsoft.OData.Edm from 8.0.2 to 8.1.0
- #1882: chore(deps): bump Microsoft.OpenApi.OData from 2.0.0-preview.5 to 2.0.0-preview.6
- #1877: Bump Verify.Xunit from 26.6.0 to 27.0.1
- #1873: Released Hidi
- #1871: Bumps up conversion lib. and hidi versions
- #1870: ci: removes zengin since he doesn't have access to the repo anymore
- #1869: Bump Microsoft.OpenApi.OData from 2.0.0-preview.3 to 2.0.0-preview.4
- #1868: Bump Microsoft.Extensions.Logging.Debug from 8.0.0 to 8.0.1
- #1867: Bump Microsoft.Extensions.Logging.Console from 8.0.0 to 8.0.1
- #1866: Sync v2 branch with the latest changes in vnext
- #1865: Bump v2 lib versions to 2.0.0-preview1
- #1863: Bump Microsoft.Extensions.Logging and Microsoft.Extensions.Logging.Abstractions
- #1862: Bump System.Text.Json from 8.0.4 to 8.0.5
- #1864: Bump Microsoft.Windows.Compatibility from 8.0.8 to 8.0.10
- #1861: Sync vnext changes with the v2 branch
- #1809: Use ConcurrentDictionary For Improving GetEnumFromDisplayName
- #1857: Avoid buffering JSON data into a new MemoryStream during parsing
- #1856: Remove validation rule to make paths and webhooks optional
- #1860: Releases Hidi
- #1859: Bumps up Hidi version
- #1858: Bump Microsoft.OpenApi.OData from 2.0.0-preview.2 to 2.0.0-preview.3
- #1826: Resolve external document dereference to OpenApiDocument using $ref to $id
- #1854: Allow hidi to transform an OpenAPI 3.1 document
- #1851: Fix $ref with $id serialization
- #1849: Set workspace baseUrl when creating a workspace
- #1820: Handle upcasting and downcasting of JSON schemas with type arrays
- #1847: Bump docker/build-push-action from 6.7.0 to 6.9.0
- #1848: Bump Microsoft.OData.Edm from 8.0.1 to 8.0.2
- #1787: Replace JsonSchema with OpenApiSchema
- #1766: Add JSON schema support
- #1729: Update packages
This list of changes was auto generated.
2.0.0-preview1
Overview
Version 2.0-preview1 brings major enhancements, including OpenAPI 3.1 support, improved performance, and bug fixes to enhance user experience. These changes introduce some breaking changes, so migrating to this new version may require updates in existing implementations.
Upgrade Steps
- Bump up Microsoft.OpenApi and Microsoft.OpenApi.Readers packages to 2.0.0-preview1 from NuGet.
Breaking Changes
1. Update namespaces
Since most of the loading code has moved to the core library, you will be required to update the namespaces in your classes to reflect the change.
Example:
If you're using an instance of our OpenApiReaderSettings
, you'll need to update the namespace from Microsoft.OpenApi.Readers
to Microsoft.OpenApi.Reader
2. Use Load/LoadAsync/Parse pattern for loading OpenApi documents
We've introduced a simplified static loading pattern for OpenAPI documents, removing the need for a secondary reader.
We have also introduced a registry class that allows users to register different OpenAPI format providers and their implementations for customized scenarios.
Reading from a JSON stream:
var settings = new OpenApiReaderSettings();
var readResult = OpenApiDocument.Load(stream, "json", settings);
var doc = readResult.OpenApiDocument;
To enable YAML parsing, you'll have to register our OpenApiYamlReader with our reader registry for us to take a dependency on the SharpYaml library.
Reading from a YAML stream:
OpenApiReaderRegistry.RegisterReader(OpenApiConstants.Yaml, new OpenApiYamlReader());
var doc = OpenApiDocument.Load(stream, "yaml", settings).OpenApiDocument;
Reading string input:
var doc = OpenApiDocument.Parse(input, "yaml").OpenApiDocument;
Reading from a file path or URL:
var doc = await OpenApiDocument.LoadAsync(filePath).OpenApiDocument;
3. Migration to JsonNode for examples and extensions
Schema examples and extensions now use JsonNode instead of IOpenApiAny, ensuring JSON Schema compatibility and fixing parsing errors.
You'll be required to import the System.Text.Json.Nodes
namespace to facilitate this.
v1.x example:
Example = new OpenApiObject
{
["name"] = new OpenApiString("Puma"),
["id"] = new OpenApiLong(1)
}
v2.0 example:
Example = new JsonObject
{
["name"] = "Puma",
["id"] = 1
}
v1.x extensions:
Extensions = new Dictionary<string, IOpenApiExtension>
{
{
"x-ms-docs-operation-type", new OpenApiString("function")
}
}
v2.0 extensions:
Extensions = new Dictionary<string, IOpenApiExtension>
{
{
"x-ms-docs-operation-type", new OpenApiAny("function")
}
}
4. JSON schema Type has changed from string to JsonSchemaType enum
In line with JSON Schema, the type
keyword can now define multiple types for a schema with an array. Swap nullable for type arrays.
Schema example in v1.x:
Type = "array",
Items = new() { Type = "string" }
Schema example in v2.0:
Type = JsonSchemaType.Array,
Items = new() { Type = JsonSchemaType.String }
5. Use Proxy Reference object in place of OpenApiReference
in your model
We have optimized the reference resolution step by implementing a proxy pattern where dereferencing happens by lazy loading when one tries to access an object's properties that contains a $ref.
Example
Items = new OpenApiSchema
{
UnresolvedReference = true,
Reference = new OpenApiReference
{
Type = ReferenceType.Schema,
Id = "GeoJSON.position"
}
}
changes to:
Items = new OpenApiSchemaReference("GeoJSON.position", null),
The proxy objects exist within the Microsoft.OpenApi.Models.References
namespace so make sure to add a reference to this in your class.
Note: For the reference to be resolved, make sure to pass a host document instance.
6. Modify validation rules to add CRUD operations
Modifies validation rules to add Create, Read, Update and Delete operations to allow for a configurable experience by clients.
New Features
-
OpenAPI 3.1 support in line with the OpenApi 3.1 specification.These include:
- Webhooks support
- summary property in the info object
- license SPDX identifier
- Add a root property JSON schema dialect
- Allow overloading of summary and description fields alongside $ref for non-JSON schema objects.
-
JSON schema support
- Support the core and validation keywords from the latest JSON schema specification JSON Schema Specification Draft 2020-12.
- Add support for keywords such as $schema, $id, $comment, $vocabulary, $dynamicRef, $dynamicAnchor.
- Swap nullable for type arrays
- Map nullable keyword to null type
- ExclusiveMinimum and ExclusiveMaximum now represent distinct values
- Add support for PatternProperties
- Support for
examples
defined as an array
-
Local and external document dereferencing using a $ref locator to schema identifiers using $id
Enhancements and Perf improvements
1. Proxy Pattern for reference resolution
Simplifies reference resolution using proxy reference objects that implement lazy loading during property access thus eliminating the need for a secondary parse.
2. System.Text.Json for parsing
Replaces older parsers with System.Text.Json to improve efficiency and native integration.
3. Optimized JSON parsing
Completely bypasses the YAML parser to parse JSON documents, significantly improving performance.
4. Avoid buffering JSON data into a new MemoryStream during parsing
This increases efficiency by reducing memory usage and allowing the program to respond faster as JSON data can be read asynchronously, especially in cases with large or streaming data.
Bug Fixes
- Fix validation errors during examples validation resulting into data type mismatches
- Fix example values and extension strings switching type
- Fix property getter that changes model data
- Fix Parsing error when path key exceeds 1023 characters by using STJ
- Fixes consumes in global context not being propagated to request body
- Fixes examples serialization in request/response objects during v2->v3 upcasting and vice versa
- Fix ValidationRuleSet.Rules should be IEnumerable not IList
- Simplify null checks
- Remove validation rule to make both paths and webhooks optional in v2.0
- Writing $ref values that have a $Id as a value are incorrectly prepending #/components/schema/
- Fix concurrency error with reader registry
Other Changes
- Update our commandline tool-hidi to validate and transform 3.1 documents
1.6.22
Changes:
- #1898: Release Hidi
- #1896: Bump up hidi and conversion lib versions
- #1895: chore(deps): bump Verify.Xunit from 27.0.1 to 27.1.0
- #1892: docs: fixes doc comments to align with changes made in #1883
- #1883: fix: emits number for integer formats
- #1886: use nameof for CallerArgumentExpression
- #1885: Release Hidi lib.
- #1884: Bump, Release Hidi
- #1881: chore(deps): bump Microsoft.OData.Edm from 8.0.2 to 8.1.0
- #1882: chore(deps): bump Microsoft.OpenApi.OData from 2.0.0-preview.5 to 2.0.0-preview.6
See More
- #1877: Bump Verify.Xunit from 26.6.0 to 27.0.1
- #1873: Released Hidi
- #1871: Bumps up conversion lib. and hidi versions
- #1870: ci: removes zengin since he doesn't have access to the repo anymore
- #1869: Bump Microsoft.OpenApi.OData from 2.0.0-preview.3 to 2.0.0-preview.4
- #1868: Bump Microsoft.Extensions.Logging.Debug from 8.0.0 to 8.0.1
- #1867: Bump Microsoft.Extensions.Logging.Console from 8.0.0 to 8.0.1
- #1863: Bump Microsoft.Extensions.Logging and Microsoft.Extensions.Logging.Abstractions
- #1862: Bump System.Text.Json from 8.0.4 to 8.0.5
- #1864: Bump Microsoft.Windows.Compatibility from 8.0.8 to 8.0.10
- #1809: Use ConcurrentDictionary For Improving GetEnumFromDisplayName
- #1860: Releases Hidi
- #1859: Bumps up Hidi version
- #1858: Bump Microsoft.OpenApi.OData from 2.0.0-preview.2 to 2.0.0-preview.3
- #1847: Bump docker/build-push-action from 6.7.0 to 6.9.0
- #1848: Bump Microsoft.OData.Edm from 8.0.1 to 8.0.2
This list of changes was auto generated.
1.6.21
1.6.20
Changes:
- #1816: Release libs
- #1815: Disable VisualStudio.Threading analyzers to eliminate build failures downstream
- #1814: Fix: Do not default to an empty list if Security scheme is missing
- #1813: Bump Moq from 4.20.70 to 4.20.71
- #1811: Bump Verify.Xunit from 26.3.0 to 26.3.1
- #1807: ci: upgrades outdated nuget installer task
- #1808: Bump Verify.Xunit from 26.2.0 to 26.3.0
- #1806: fix: directly adds non-vulnerable versions of transitive deps to resolve alerts
- #1805: Investigate: Check whether server info changes during slicing
This list of changes was auto generated.
1.6.19
Changes:
- #1802: Release hidi and libs
- #1803: Copy over references for all IOpenApiReferenceable objects
- #1801: Bump hidi and lib versions
- #1759: Use ConcurrentDictionary For Improving Get Enum Name
- #1800: Fix: Remove minimatch pattern to sign all assemblies
- #1798: chore/tasks linting
This list of changes was auto generated.
1.6.18
Changes:
- #1795: Release libs.
- #1794: Update OData lib and Hidi versions
- #1783: Add server variable substitution logic.
- #1788: Bump Microsoft.NET.Test.Sdk from 17.10.0 to 17.11.0
- #1785: Bump Microsoft.OData.Edm from 8.0.0 to 8.0.1
- #1784: Bump docker/build-push-action from 6.6.1 to 6.7.0
- #1782: Bump Newtonsoft.Json from 13.0.1 to 13.0.3
- #1780: Bump Microsoft.Windows.Compatibility from 8.0.7 to 8.0.8
- #1777: Bump docker/build-push-action from 6.5.0 to 6.6.1
- #1778: Bump Verify.Xunit from 26.1.6 to 26.2.0
See More
- #1779: Bump Microsoft.OData.Edm from 7.21.3 to 8.0.0
- #1776: Master Refresh
- #1775: Upgrade ESRPCodeSigning tasks
- #1774: Fix examples serialization causing NullReferenceException
This list of changes was auto generated.