Microsoft.OpenApi.Readers 1.6.23

Prefix Reserved
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package Microsoft.OpenApi.Readers --version 1.6.23                
NuGet\Install-Package Microsoft.OpenApi.Readers -Version 1.6.23                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Microsoft.OpenApi.Readers" Version="1.6.23" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Microsoft.OpenApi.Readers --version 1.6.23                
#r "nuget: Microsoft.OpenApi.Readers, 1.6.23"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Microsoft.OpenApi.Readers as a Cake Addin
#addin nuget:?package=Microsoft.OpenApi.Readers&version=1.6.23

// Install Microsoft.OpenApi.Readers as a Cake Tool
#tool nuget:?package=Microsoft.OpenApi.Readers&version=1.6.23                

Category overview screenshot

OpenAPI.NET

Package Nuget
Models and Writers nuget
Readers nuget
Hidi 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: <a href="https://www.openapis.org">OpenAPI Initiative</a>

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

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 Dictionary<OperationType, OpenApiOperation>
            {
                [OperationType.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 httpClient = new HttpClient
{
    BaseAddress = new Uri("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/")
};

var stream = await httpClient.GetStreamAsync("master/examples/v3.0/petstore.yaml");

// Read V3 as YAML
var openApiDocument = new OpenApiStreamReader().Read(stream, out var diagnostic);

// Write V2 as JSON
var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, OpenApiFormat.Json);

Validating/Testing OpenAPI descriptions

In order to test the validity of an OpenApi document, we avail the following tools:

  • Microsoft.OpenApi.Hidi

    A commandline tool for validating and transforming OpenAPI descriptions. Installation guidelines and documentation

  • Microsoft.OpenApi.Workbench

    A workbench tool consisting of a GUI where you can test and convert OpenAPI descriptions in both JSON and YAML from v2-->v3 and vice versa.

    Installation guidelines:
    1. Clone the repo locally by running this command: git clone https://github.com/microsoft/OpenAPI.NET.git
    2. Open the solution file (.sln) in the root of the project with Visual Studio
    3. Navigate to the src/Microsoft.OpenApi.Workbench directory and set it as the startup project
    4. Run the project and you'll see a GUI pop up resembling the one below:

    <img src="https://user-images.githubusercontent.com/36787645/235884441-f45d2ef7-c27b-4e1a-a890-d6f7fbef87c3.png" width="700" height="500">

    1. Copy and paste your OpenAPI descriptions in the Input Content window or paste the path to the descriptions file in the Input File textbox and click on Convert to render the results.

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.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (83)

Showing the top 5 NuGet packages that depend on Microsoft.OpenApi.Readers:

Package Downloads
WireMock.Net.OpenApiParser

An OpenApi (swagger) parser to generate MappingModel or mapping.json file.

RamlToOpenApiConverter

Convert RAML file to Open API Specification

OasReader

An OpenAPI reader that merges external references into a single document for .NET using the [Microsoft OpenAPI](https://www.nuget.org/packages/Microsoft.OpenApi.readers) toolset

Microsoft.OpenApi.CSharpAnnotations.DocumentGeneration

Library that translates Visual Studio C# Annotations into .NET objects representing OpenAPI specification.

Microsoft.OpenApi.ApiManifest

Package Description

GitHub repositories (28)

Showing the top 5 popular GitHub repositories that depend on Microsoft.OpenApi.Readers:

Repository Stars
microsoft/semantic-kernel
Integrate cutting-edge LLM technology quickly and easily into your apps
chocolatey/choco
Chocolatey - the package manager for Windows
EventStore/EventStore
EventStoreDB, the event-native database. Designed for Event Sourcing, Event-Driven, and Microservices architectures
ChilliCream/graphql-platform
Welcome to the home of the Hot Chocolate GraphQL server for .NET, the Strawberry Shake GraphQL client for .NET and Nitro the awesome Monaco based GraphQL IDE.
domaindrivendev/Swashbuckle.AspNetCore
Swagger tools for documenting API's built on ASP.NET Core
Version Downloads Last updated
2.0.0-preview3 54 12/20/2024
2.0.0-preview2 401 11/12/2024
2.0.0-preview1 148 11/6/2024
1.6.23 668 12/20/2024
1.6.22 396,810 9/30/2024
1.6.21 193,738 9/5/2024
1.6.18 114,868 8/23/2024
1.6.17 177,508 8/6/2024
1.6.16 90,015 7/30/2024
1.6.15 218,864 6/18/2024
1.6.14 812,268 3/6/2024
1.6.13 509,998 1/29/2024
1.6.12 365,066 1/16/2024
1.6.11 1,616,911 11/22/2023
1.6.10 323,009 10/30/2023
1.6.9 245,072 9/26/2023
1.6.8 154,039 9/7/2023
1.6.7 32,310 9/1/2023
1.6.6 775,607 7/24/2023
1.6.5 231,493 6/19/2023
1.6.4 240,200 5/4/2023
1.6.4-preview4 4,579 4/17/2023
1.6.4-preview3 217 4/12/2023
1.6.4-preview2 214 4/11/2023
1.6.4-preview1 494 3/30/2023
1.6.3 751,727 3/7/2023
1.6.2 138,173 2/21/2023
1.6.1 66,519 2/13/2023
1.6.0 95,131 1/31/2023
1.5.0 60,997 1/17/2023
1.4.5 1,672,952 12/6/2022
1.4.4 67,687 11/21/2022
1.4.4-preview1 970 10/6/2022
1.4.1 236,428 9/12/2022
1.4.0 74,941 9/2/2022
1.4.0-preview3 213 9/2/2022
1.4.0-preview2 469 8/15/2022
1.4.0-preview1 508 8/1/2022
1.3.2 617,099 6/23/2022
1.3.1 530,338 4/13/2022
1.3.1-preview6 574 4/10/2022
1.3.1-preview5 7,146 3/3/2022
1.3.1-preview4 17,935 2/8/2022
1.3.0-preview 97,076 5/25/2021
1.2.3 10,870,678 8/29/2020
1.2.2 143,700 6/25/2020
1.2.1 718 6/24/2020
1.2.0 26,325 6/14/2020
1.2.0-preview.3 13,654 4/2/2020
1.2.0-preview.2 3,266 3/9/2020
1.2.0-preview 774 1/20/2020
1.1.4 897,819 9/15/2019
1.1.3 678,939 4/19/2019
1.1.2 170,200 12/13/2018
1.1.1 462,553 10/24/2018
1.1.0 56,478 8/16/2018
1.1.0-preview.4 975 7/18/2018
1.1.0-preview.3 5,451 6/14/2018
1.1.0-preview.2 775 6/7/2018
1.1.0-preview.1 794 5/25/2018
1.0.1 15,536 5/25/2018
1.0.0 17,705 5/8/2018
1.0.0-beta017 1,149 5/2/2018
1.0.0-beta016 1,856 4/8/2018
1.0.0-beta015 1,527 3/21/2018
1.0.0-beta014 2,683 2/13/2018
1.0.0-beta013 1,190 1/31/2018
1.0.0-beta012 1,077 1/24/2018
1.0.0-beta011 1,450 1/16/2018
1.0.0-beta010 1,067 1/11/2018
1.0.0-beta009 1,363 12/20/2017
1.0.0-beta008 1,147 12/14/2017