OpenAPI.NET v2 & v3: Major Updates Delivering Enhanced API Specification Support

We are pleased to announce the release of OpenAPI.NET v2 and v3, marking the most significant updates to the library since its inception in 2018. These releases empower developers to build and document modern, interoperable APIs fully aligned with the latest OpenAPI specifications.

OpenAPI.NET v2

This version introduces comprehensive support for OpenAPI Specification v3.1.0. Key improvements include:

• OpenAPI Spec v3.1 Support: Full serialization and model capabilities.
• API Surface Enhancements: Improved API surface for properties of type "json," now leveraging the native JSON node API.
• Performance Gains: Faster JSON parsing utilizing System.Text.Json while maintaining YAML support. Our benchmarks indicate an overall 50% reduction in processing time for document parsing and a 35% reduction in memory allocation when parsing JSON.
• Lazy Reference Resolution: Optimized load times for documents with extensive $ref usage.
• Reduced Dependencies: The core library can now read and write JSON without requiring additional packages.

OpenAPI.NET v3

Version 3 delivers full support for OpenAPI Specification v3.2.0, along with new features such as:

• OpenAPI Spec v3.2 Support: Complete serialization and model support.
• Enhanced Media Types: New properties for encoding and schema support.
• Hierarchical Tags: Support for organizing tags with kind, summary, and parent relationships.
• Security Enhancements: Includes support for deprecated flags and device authorization flows.
• Enhanced Examples: New data value and serialized value properties.
• Extended Parameter Support: Introduces new locations and styles for parameters.

Impact on the .NET Ecosystem

OpenAPI.NET serves as a foundational library for many critical .NET tools and frameworks, including Swashbuckle, Semantic Kernel, NSwag, and .NET itself. These updates are crucial for:

• Future-proofing API documentation for ASP.NET Core projects, especially as .NET 10 progresses towards native OpenAPI support.
• Improving performance and reliability for large-scale API ecosystems.

Upgrade Guides

For a comprehensive list of new features and detailed developer guides for updating your existing projects, please refer to the dedicated upgrade guides. We recommend upgrading to v2 first, then subsequently to v3.

Support and Contributions

OpenAPI.NET is an open-source project that thrives on community contributions. We welcome and appreciate involvement from all developers passionate about the OpenAPI initiative. Please consult the contributing guide before making new contributions.

Feedback and contributions are welcome via GitHub issues.