Microsoft.OpenApi 3.11.1

Category overview screenshot

OpenAPI.NET

Package Nuget
Models and Writers nuget
YamlReader nuget

The OpenAPI.NET SDK contains a useful object model for OpenAPI documents in .NET along with common serializers to extract raw OpenAPI JSON and YAML documents from the model.

See more information on the OpenAPI specification and its history here: OpenAPI Initiative

Project Objectives:

  • Provide a single shared object model in .NET for OpenAPI descriptions.
  • Include the most primitive Reader for ingesting OpenAPI JSON and YAML documents in both V2 and V3 formats.
  • Provide OpenAPI description writers for both V2 and V3 specification formats.
  • Enable developers to create Readers that translate different data formats into OpenAPI descriptions.

Installation

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.

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.

The base JSON and YAML processors are built into this project. Below is the list of the other supported processor projects.

  • C# Comment / Annotation Processor : Converts standard .NET annotations ( /// comments ) emitted from your build (MSBuild.exe) into OpenAPI.NET document object.

  • OData CSDL Processor : Converts the XML representation of the Entity Data Model (EDM) describing an OData Service into OpenAPI.NET document object.

Example Usage

Creating an OpenAPI Document

var document = new OpenApiDocument
{
    Info = new OpenApiInfo
    {
        Version = "1.0.0",
        Title = "Swagger Petstore (Simple)",
    },
    Servers = new List<OpenApiServer>
    {
        new OpenApiServer { Url = "http://petstore.swagger.io/api" }
    },
    Paths = new OpenApiPaths
    {
        ["/pets"] = new OpenApiPathItem
        {
            Operations = new()
            {
                [HttpMethod.Get] = new OpenApiOperation
                {
                    Description = "Returns all pets from the system that the user has access to",
                    Responses = new OpenApiResponses
                    {
                        ["200"] = new OpenApiResponse
                        {
                            Description = "OK"
                        }
                    }
                }
            }
        }
    }
};

Reading and writing an OpenAPI description

var (openApiDocument, _) = await OpenApiDocument.LoadAsync("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/heads/main/_archive_/schemas/v3.0/pass/petstore.yaml");

// Write V2 as JSON
var outputString = await openApiDocument.SerializeAsJsonAsync(OpenApiSpecVersion.OpenApi2_0);

External references are loaded only when OpenApiReaderSettings.LoadExternalRefs is enabled. MaxExternalReferenceDepth defaults to 64 external document hops (the root is depth zero) and can be set to a higher positive value for deeper descriptions. It is independent of JSON/YAML nesting limits. External documents are reused within a load, allowing valid recursive schemas across files without repeated requests. Exceeding the depth limit or encountering an external reference-only loop returns a ReadResult with a null Document and an error in Diagnostic.Errors. Annotation-only siblings, such as description, do not exempt a reference from loop detection.

Validating/Testing OpenAPI descriptions

Microsoft.OpenApi.Hidi is a command line tool for validating and transforming OpenAPI descriptions. The OpenAPI.NET v3-compatible tool is maintained in OpenAPI.NET.OData's main branch. See its installation guidelines and documentation.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

To provide feedback and ask questions you can use Stack Overflow with the OpenAPI.NET tag.

Showing the top 20 packages that depend on Microsoft.OpenApi.

Packages Downloads
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/d47e49e9c1e173ac90821f7e89cc38e710274241
32
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/d9ba962869d1b1c410ea476b02de2f8e27eec762
26
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/31d685b2d9a86ca1243014d175a3da813f78e428
17
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/3dfc6fda80a10797b8c8fda1970e7b377fd8ed8d
17
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/c2a442982e736e17ae6bcadbfd8ccba278ee1be6
16
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/cb14812a5c6098bd1091f5b7fd471ce2be45e8dd
16
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/f0cc6b11bd8f0826c63d75483578e868c8abe75e
15
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/e77cb01b5529c137130757859f09f892dbdd2436
14
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/3c37ef8f5358abb303c05d299f029fca7d867d56
14
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/dotnet/tree/a8b33e7593686eaee701cd124daaabff2311634f
14
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/bb01bbf4433e27289b99001b7de6a582879d1835
13
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/2f1db20456007c9515068a35a65afdf99af70bc6
13
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/c9e3996173cec136bc2e9f3b4ec45f2a323b1d63
13
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/fe4f0d09305ca73aa19976b4521e5c4e223b080e
12
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/b8139c5ee58f1708b0e3368a1b241400edd6cbc4
12
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/cccab50fba1c7335fdb48a735246374b5ddd7e69
12
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/898c164a1f537a8210a26eaf388bdc92531f6b09
12
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/47576478939fdd59b4400ad135f47938af486ab3
12
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/70048beee894074e9718206a0017d9b080ee66ff
12
Microsoft.AspNetCore.OpenApi
Provides APIs for annotating route handler endpoints in ASP.NET Core with OpenAPI annotations. This package was built from the source code at https://github.com/dotnet/aspnetcore/tree/4ae1269bff83362236d0f3bd4c9302e6a1e9341c
12

https://github.com/microsoft/OpenAPI.NET/releases

.NET 8.0

  • No dependencies.

.NET Standard 2.0

Version Downloads Last updated
3.11.1 3 11/17/2026
3.11.0 8 10/27/2026
3.10.2 5 09/22/2026
3.10.0 9 09/22/2026
3.9.0 8 07/26/2026
3.8.0 8 07/18/2026
3.7.0 7 07/17/2026
3.6.0 8 07/16/2026
3.5.5 8 05/30/2026
3.5.4 7 05/30/2026
3.5.3 7 05/30/2026
3.5.2 9 04/16/2026
3.5.1 8 04/04/2026
3.5.0 9 03/28/2026
3.4.0 10 03/10/2026
3.3.1 2 01/27/2026
3.3.0 4 01/28/2026
3.2.0 4 01/23/2026
3.1.3 4 01/25/2026
3.1.2 8 01/09/2026
3.1.1 3 12/23/2025
3.0.3 1 12/23/2025
3.0.2 2 12/15/2025
3.0.1 2 12/10/2025
3.0.0 2 12/16/2025
2.13.1 2 11/17/2026
2.13.0 6 10/26/2026
2.12.2 7 09/22/2026
2.12.1 7 09/22/2026
2.12.0 6 09/17/2026
2.11.0 5 07/26/2026
2.10.0 8 07/17/2026
2.9.0 6 07/16/2026
2.8.0 7 07/19/2026
2.7.6 7 05/30/2026
2.7.5 8 05/30/2026
2.7.4 9 05/30/2026
2.7.3 7 04/16/2026
2.7.2 8 04/05/2026
2.7.1 9 03/28/2026
2.7.0 10 03/10/2026
2.6.1 2 01/28/2026
2.6.0 3 01/27/2026
2.5.0 4 01/26/2026
2.4.3 2 01/26/2026
2.4.2 3 01/10/2026
2.4.1 2 12/23/2025
2.4.0 2 12/23/2025
2.3.12 1 12/17/2025
2.3.11 2 12/16/2025
2.3.10 1 12/17/2025
2.3.9 2 12/16/2025
2.3.8 1 12/17/2025
2.3.7 2 12/09/2025
2.3.6 1 12/17/2025
2.3.5 1 12/17/2025
2.3.4 2 12/16/2025
2.3.3 1 12/17/2025
2.3.2 1 12/17/2025
2.3.1 2 12/17/2025
2.3.0 1 12/17/2025
2.2.0 2 12/10/2025
2.1.0 1 12/17/2025
2.0.1 2 12/09/2025
2.0.0 1 12/17/2025
2.0.0-preview9 1 12/09/2025
2.0.0-preview4 1 12/11/2025
2.0.0-preview10 2 12/11/2025
2.0.0-preview.31 1 01/08/2026
2.0.0-preview.30 3 01/08/2026
2.0.0-preview.29 1 12/09/2025
2.0.0-preview.28 1 12/10/2025
2.0.0-preview.27 1 12/11/2025
2.0.0-preview.26 1 12/25/2025
2.0.0-preview.25 1 12/10/2025
2.0.0-preview.23 1 12/24/2025
2.0.0-preview.22 1 12/24/2025
2.0.0-preview.21 1 12/11/2025
2.0.0-preview.20 1 12/11/2025
2.0.0-preview.19 1 12/25/2025
2.0.0-preview.18 1 12/25/2025
2.0.0-preview.17 1 12/11/2025
2.0.0-preview.16 1 12/25/2025
2.0.0-preview.15 2 12/09/2025
2.0.0-preview.14 1 12/11/2025
2.0.0-preview.13 1 12/25/2025
2.0.0-preview.12 1 12/25/2025
2.0.0-preview.11 1 12/25/2025
1.6.31 5 09/20/2026
1.6.30 8 09/22/2026
1.6.29 6 04/22/2026
1.6.28 2 12/16/2025
1.6.27 1 12/17/2025
1.6.26 1 12/17/2025
1.6.25 1 12/17/2025
1.6.24 1 12/17/2025
1.6.23 1 12/17/2025
1.6.22 1 12/17/2025
1.6.21 1 12/17/2025
1.6.18 1 12/17/2025
1.6.17 1 12/17/2025
1.6.16 1 12/17/2025
1.6.15 1 12/17/2025
1.6.14 1 12/17/2025
1.6.13 1 12/17/2025
1.6.12 1 12/17/2025
1.6.11 1 12/17/2025
1.6.10 1 12/17/2025
1.6.9 1 12/17/2025
1.6.8 12 12/11/2025
1.6.7 15 12/17/2025
1.6.6 10 12/17/2025
1.6.5 8 12/17/2025
1.6.4 11 12/17/2025
1.6.4-preview4 8 01/01/2026
1.6.4-preview3 10 12/11/2025
1.6.4-preview2 9 12/25/2025
1.6.4-preview1 10 12/10/2025
1.6.3 10 12/17/2025
1.6.2 9 12/17/2025
1.6.1 11 12/17/2025
1.6.0 8 12/10/2025
1.5.0 10 12/17/2025
1.4.5 12 12/17/2025
1.4.4 10 12/17/2025
1.4.4-preview1 8 12/25/2025
1.4.3 10 12/17/2025
1.4.2 10 12/17/2025
1.4.1 12 12/17/2025
1.4.0 11 12/09/2025
1.4.0-preview3 8 01/01/2026
1.4.0-preview2 10 12/11/2025
1.4.0-preview1 10 12/25/2025
1.3.2 10 12/17/2025
1.3.1 10 12/17/2025
1.3.1-preview6 8 12/25/2025
1.3.1-preview5 9 12/25/2025
1.3.1-preview4 6 01/01/2026
1.3.1-preview3 8 12/25/2025
1.3.1-preview2 9 12/25/2025
1.3.1-preview 10 12/17/2025
1.3.0-preview 11 12/17/2025
1.2.3 10 12/17/2025
1.2.2 10 12/17/2025
1.2.1 12 12/17/2025
1.2.0 9 12/17/2025
1.2.0-preview.3 11 12/09/2025
1.2.0-preview.2 10 12/25/2025
1.2.0-preview 11 12/17/2025
1.1.4 10 12/17/2025
1.1.3 9 12/17/2025
1.1.2 12 12/17/2025
1.1.1 11 12/17/2025
1.1.0 9 12/17/2025
1.1.0-preview.4 10 12/25/2025
1.1.0-preview.3 10 12/25/2025
1.1.0-preview.2 7 12/25/2025
1.1.0-preview.1 9 12/24/2025
1.0.1 10 12/09/2025
1.0.0 9 12/17/2025
1.0.0-beta017 21 12/25/2025
1.0.0-beta016 10 12/25/2025
1.0.0-beta015 8 01/01/2026
1.0.0-beta014 9 12/25/2025
1.0.0-beta013 9 12/11/2025
1.0.0-beta012 9 12/25/2025
1.0.0-beta011 10 12/25/2025
1.0.0-beta010 9 12/11/2025
1.0.0-beta009 10 12/09/2025
1.0.0-beta008 11 01/01/2026