OpenAPI.NET for .NET document modeling, serialization, and format conversion

OpenAPI.NET's .NET document model

OpenAPI.NET addresses a specific problem in .NET software that creates, consumes, or transforms OpenAPI descriptions. It represents an OpenAPI document as an object graph instead of requiring every component to work directly with JSON or YAML text. The README defines the objective as providing "a single shared object model in .NET for OpenAPI descriptions."

That model is intended for developers building tools, services, and integrations around HTTP API descriptions. A document contains an `Info` object, `Servers`, `Paths`, and the objects needed to describe operations and responses. The example defines a `/pets` path and places a `GET` operation in its `Operations` collection. The response is indexed by its HTTP status code, while operations are indexed by `HttpMethod`. These are concrete choices in the public object model rather than a thin wrapper around a parser call.

The project supports both OpenAPI V2 and V3 formats. Its stated objectives also include writers for both versions and extension points for developers who want to translate other data formats into the same model. The README lists processors for C# XML documentation comments and OData CSDL as separate projects. This processor-oriented architecture is the central reason to consider OpenAPI.NET: a format-specific component can produce the shared representation without forcing every downstream tool to understand that source format.

It is not presented as an HTTP server framework, request validator, or documentation site generator. Its responsibility begins and ends around the OpenAPI object model and its common serializers. That boundary matters when selecting it for a codebase that also needs runtime request validation or code generation, because those separate responsibilities are not established by this repository.

How OpenAPI.NET loads and writes documents

The README describes base JSON and YAML processors as built in. A consumer can load a description into an `OpenApiDocument`, work with its typed properties and collections, and then select an OpenAPI version and output format. Its loading example calls `OpenApiDocument.LoadAsync` with a URL ending in `petstore.yaml`. It returns a tuple containing `openApiDocument` and a second value represented by `_`.

The writer example then calls `SerializeAsJsonAsync` with `OpenApiSpecVersion.OpenApi2_0`. The version argument is significant: OpenAPI.NET supports V2 and V3, so serialization is not presented as a format-only choice that always emits the document's original version. The package table separates the core model and writers from the YAML reader through the `Microsoft.OpenApi` and `Microsoft.OpenApi.YamlReader` packages.

This creates a straightforward data flow. A JSON or YAML processor reads source text into the object model. Application code can inspect or modify that model. A writer serializes the resulting graph as JSON or YAML and for a selected OpenAPI specification version. The README does not describe reference resolution, diagnostic collection, schema validation, conversion error recovery, or the semantic difference represented by the tuple's second item. Those details should be checked in project documentation before an application depends on them.

The model also serves as an integration boundary. The README says developers can create Readers that translate different formats into OpenAPI descriptions. Its separate annotation and OData processors demonstrate that concept, although neither is part of the core repository. This makes OpenAPI.NET useful when one downstream component must consume descriptions originating in several formats.

Installing the OpenAPI.NET NuGet packages

Installation is distributed through NuGet rather than a command documented in the README. The core package, `Microsoft.OpenApi`, contains the model and writers. Applications that need the repository's YAML reader are directed to the separate `Microsoft.OpenApi.YamlReader` package. The README does not provide a `dotnet` installation command or a versioned package invocation, so the package names are the only installation details asserted here.

For a first real use, install both packages when the application must ingest YAML and then create or serialize a document in C#. The README states that the core package is available through NuGet as `Microsoft.OpenApi`, and the YAML-specific package is available as `Microsoft.OpenApi.YamlReader`.

After adding the required packages, start with the documented object-model example. This code constructs an `OpenApiDocument`, assigns version `1.0.0`, names the document "Swagger Petstore (Simple)", defines a server, and describes a `GET /pets` operation with an `OK` response.

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()

The README continues with the operation and response definitions, giving the complete construction as follows:

            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"
                        }
                    }
                }
            }
        }
    }
};

The README does not document application startup, dependency injection registration, configuration files, or package compatibility requirements beyond its link to the OpenAPI 3.2 upgrade guide. Those are concrete items to verify in the target project rather than assumptions about the package.

Loading YAML and serializing OpenAPI V2 JSON

The repository's end-to-end example loads a YAML description from a raw GitHub URL and serializes the resulting object as OpenAPI V2 JSON. This is a useful first workflow for code that needs to normalize an existing description.

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

After `LoadAsync` completes, `openApiDocument` is the typed document model. The README does not state what the second tuple item contains or document its inspection in this example, so the example intentionally assigns it to `_`.

The serialization call selects JSON output and `OpenApi2_0` as the specification version:

var outputString = await openApiDocument.SerializeAsJsonAsync(OpenApiSpecVersion.OpenApi2_0);

This demonstrates serialization against the V2 model. The README does not claim lossless round-tripping, explain how unsupported V3 constructs are handled, or state whether all source information is retained after conversion. For production use, compare the output with the expected contract and inspect the project's upgrade and serializer documentation for the behavior of the selected versions.

The input URL is a remote `petstore.yaml` file from the OpenAPI Specification repository. A deployed application will need the network access and trust model appropriate to wherever that source is hosted. The README also indicates that YAML support is associated with `Microsoft.OpenApi.YamlReader`, so confirm that the application references that package when this workflow is required.

Validation through Microsoft.OpenApi.Hidi

OpenAPI.NET should not be confused with a complete OpenAPI validation and transformation command-line suite. The README sends validation and transformation work to `Microsoft.OpenApi.Hidi`, a separate command-line tool. It also says the OpenAPI.NET v3-compatible tool is maintained in the main branch of the OpenAPI.NET.OData repository, with installation guidance and documentation located in that repository's `Microsoft.OpenApi.Hidi` readme.

That separation affects adoption decisions. A team whose primary need is to check whether an OpenAPI description is valid should examine Microsoft.OpenApi.Hidi first. A team that needs to embed typed OpenAPI objects, modify descriptions, read JSON or YAML, and emit selected specification versions belongs in OpenAPI.NET's core use case.

The distinction also affects deployment. The SDK is presented as a set of .NET packages and an object model, while Hidi is a command-line utility. The README does not document an in-process validation API in the SDK, nor does it describe Hidi's exact commands. An application should therefore avoid implying that constructing or serializing an `OpenApiDocument` establishes semantic validity of the resulting description.

For pipelines, the two projects can have different roles without contradiction. OpenAPI.NET can model or transform a document, and Microsoft.OpenApi.Hidi can serve as the validation and command-line transformation layer. The README makes that separation explicit, but it does not provide a documented pipeline example, so integration details must come from Hidi's own documentation.

OpenAPI.NET maintenance, licensing, and upgrade cost

The repository is not archived, and its last push was on 2026-10-15. The listed releases include `v3.10.2` on 2026-08-20, `v2.12.2` on 2026-08-20, and `v1.6.31` on 2026-08-20. Those facts show recent repository and release activity, but they do not establish compatibility or production suitability for a particular .NET application.

OpenAPI.NET uses the MIT license. That is a permissive software license, but this review does not interpret its legal effect. Teams still need to review package dependencies, notices, internal policies, and the exact terms associated with the versions they ship.

Upgrade planning has a concrete cost because the README announces a new major version with OpenAPI 3.2 support and directs users to `docs/upgrade-guide-3.md`. Code written against earlier APIs may need changes even if the package remains under the `Microsoft.OpenApi` name. The repository also contains `CHANGELOG.md`, which is the relevant file for release-specific changes, although the README does not summarize those changes.

Applications should not assume that the repository's `v1`, `v2`, and `v3` release labels are identical to OpenAPI document versions without checking release notes. The example explicitly uses `OpenApiSpecVersion.OpenApi2_0`, while the README separately refers to a new major library version with OpenAPI 3.2 support. Package release versioning and emitted OpenAPI specification versioning are related concerns, but the README does not define them as identical numbering schemes.

Choosing between OpenAPI.NET and direct document handling

The main alternative is to work directly with JSON or YAML through a general-purpose data format library, schema library, or custom parser. The approach differs at the first boundary. OpenAPI.NET exposes a named OpenAPI object graph with types such as `OpenApiDocument`, `OpenApiOperation`, `OpenApiResponse`, and `OpenApiPaths`. A direct-data approach leaves the application responsible for representing paths, operations, responses, versions, and serialization conventions itself.

Direct handling can be appropriate when an application only performs a narrow text transformation and does not need an OpenAPI-specific object model. OpenAPI.NET is the clearer choice when several tools need to share one representation, when code must emit both OpenAPI V2 and V3, or when another input format must be converted into the same model. The repository's processor objectives and listed external processors are concrete evidence of this intended use.

There is also a separate alternative for command-line validation and transformation: Microsoft.OpenApi.Hidi. Compared with embedding OpenAPI.NET, Hidi moves the operation into a command-line tool rather than application code. That can reduce the need for SDK integration, although the README does not provide enough command documentation to compare its feature set or deployment requirements in detail.

OpenAPI.NET is the wrong choice when the requirement is limited to editing arbitrary YAML while preserving formatting and comments, because the README does not claim formatting-preserving edits. It is also a poor substitute for an HTTP runtime validator, a documentation renderer, or a code generator. None of those functions is assigned to this repository.

Editorial conclusion

Adopt OpenAPI.NET when a .NET application needs a typed model, reads OpenAPI JSON or YAML, or writes V2 and V3 output. Do not choose it solely as a validator, because validation and transformation are assigned to Microsoft.OpenApi.Hidi. Before upgrading, check `docs/upgrade-guide-3.md` and verify that the selected package version supports the OpenAPI features required by the application.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. microsoft/OpenAPI.NET on GitHub
4. README
5. Releases