Microsoft.OpenApi 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 --version 1.6.23                
NuGet\Install-Package Microsoft.OpenApi -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" 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 --version 1.6.23                
#r "nuget: Microsoft.OpenApi, 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 as a Cake Addin
#addin nuget:?package=Microsoft.OpenApi&version=1.6.23

// Install Microsoft.OpenApi as a Cake Tool
#tool nuget:?package=Microsoft.OpenApi&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.
  • .NETStandard 2.0

    • No dependencies.

NuGet packages (275)

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

Package Downloads
Swashbuckle.AspNetCore.Swagger

Middleware to expose Swagger JSON endpoints from APIs built on ASP.NET Core

Swashbuckle.AspNetCore.Filters

Some additional useful filters for Swashbuckle.AspNetCore. This package replaces Swashbuckle.AspNetCore.Examples.

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/af22effae4069a5dfb9b0735859de48820104f5b

Microsoft.OpenApi.Readers

OpenAPI.NET Readers for JSON and YAML documents

Microsoft.Azure.WebJobs.Extensions.OpenApi.Core

This package helps render OpenAPI document and Swagger UI of Azure Functions endpoints through the in-process worker.

GitHub repositories (44)

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

Repository Stars
microsoft/semantic-kernel
Integrate cutting-edge LLM technology quickly and easily into your apps
chocolatey/choco
Chocolatey - the package manager for Windows
ServiceStack/ServiceStack
Thoughtfully architected, obscenely fast, thoroughly enjoyable web services for all
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-preview4 0 12/24/2024
2.0.0-preview3 191 12/20/2024
2.0.0-preview2 1,988 11/12/2024
2.0.0-preview1 506 11/6/2024
1.6.23 4,845 12/20/2024
1.6.22 4,402,006 9/30/2024
1.6.21 443,669 9/5/2024
1.6.18 237,095 8/23/2024
1.6.17 1,209,195 8/6/2024
1.6.16 219,249 7/30/2024
1.6.15 763,293 6/18/2024
1.6.14 44,900,673 3/6/2024
1.6.13 1,546,503 1/29/2024
1.6.12 589,789 1/16/2024
1.6.11 2,501,063 11/22/2023
1.6.10 890,862 10/30/2023
1.6.9 725,195 9/26/2023
1.6.8 344,354 9/7/2023
1.6.7 121,338 9/1/2023
1.6.6 1,465,490 7/24/2023
1.6.5 813,127 6/19/2023
1.6.4 1,024,692 5/4/2023
1.6.4-preview4 16,883 4/17/2023
1.6.4-preview3 1,730 4/12/2023
1.6.4-preview2 10,833 4/11/2023
1.6.4-preview1 19,327 3/30/2023
1.6.3 1,707,643 3/7/2023
1.6.2 499,800 2/21/2023
1.6.1 245,369 2/13/2023
1.6.0 349,133 1/31/2023
1.5.0 327,385 1/17/2023
1.4.5 2,623,518 12/6/2022
1.4.4 482,363 11/21/2022
1.4.4-preview1 17,027 10/6/2022
1.4.3 41,993,814 9/26/2022
1.4.2 479,625 9/12/2022
1.4.1 106,692 9/7/2022
1.4.0 274,875 9/2/2022
1.4.0-preview3 1,584 9/2/2022
1.4.0-preview2 15,240 8/15/2022
1.4.0-preview1 6,986 8/1/2022
1.3.2 2,419,487 6/23/2022
1.3.1 29,712,851 4/13/2022
1.3.1-preview6 2,157 4/10/2022
1.3.1-preview5 15,879 3/3/2022
1.3.1-preview4 26,410 2/8/2022
1.3.1-preview3 1,902 2/3/2022
1.3.1-preview2 6,214 1/23/2022
1.3.1-preview 27,203 11/25/2021
1.3.0-preview 284,588 5/25/2021
1.2.3 476,582,691 8/29/2020
1.2.2 10,199,172 6/25/2020
1.2.1 3,049 6/24/2020 1.2.1 is deprecated because it has critical bugs.
1.2.0 42,166 6/14/2020 1.2.0 is deprecated because it has critical bugs.
1.2.0-preview.3 15,852 4/2/2020
1.2.0-preview.2 4,346 3/9/2020
1.2.0-preview 5,110 1/20/2020
1.1.4 89,144,008 9/15/2019
1.1.3 1,925,093 4/19/2019
1.1.2 1,300,799 12/13/2018
1.1.1 12,929,156 10/24/2018
1.1.0 86,667 8/16/2018
1.1.0-preview.4 1,439 7/18/2018
1.1.0-preview.3 6,051 6/14/2018
1.1.0-preview.2 1,014 6/7/2018
1.1.0-preview.1 972 5/25/2018
1.0.1 18,717 5/25/2018
1.0.0 41,221 5/8/2018
1.0.0-beta017 2,638 5/2/2018
1.0.0-beta016 3,471 4/8/2018
1.0.0-beta015 2,996 3/21/2018
1.0.0-beta014 5,646 2/13/2018
1.0.0-beta013 2,545 1/31/2018
1.0.0-beta012 3,016 1/24/2018
1.0.0-beta011 2,893 1/16/2018
1.0.0-beta010 2,509 1/11/2018
1.0.0-beta009 2,820 12/20/2017
1.0.0-beta008 2,662 12/14/2017