Microsoft.OpenApi 1.6.9

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
.NET Standard 2.0
dotnet add package Microsoft.OpenApi --version 1.6.9
NuGet\Install-Package Microsoft.OpenApi -Version 1.6.9
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.9" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Microsoft.OpenApi --version 1.6.9
#r "nuget: Microsoft.OpenApi, 1.6.9"
#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.9

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

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.

Build Status

master
Build status

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 or use the OpenAPI.NET Slack channel which you can join by registering for the HTTP APIs team at http://slack.httpapis.com.

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. 
.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)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.0

    • No dependencies.

NuGet packages (200)

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.OpenApi.Readers The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

OpenAPI.NET Readers for JSON and YAML documents

Microsoft.AspNetCore.OpenApi The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

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/8ad057426fa6a27cd648b05684afddab9d97d3d9

Microsoft.Azure.WebJobs.Extensions.OpenApi.Core The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

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

GitHub repositories (31)

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
domaindrivendev/Swashbuckle.AspNetCore
Swagger tools for documenting API's built on ASP.NET Core
fanliang11/surging
Surging is a micro-service engine that provides a lightweight, high-performance, modular RPC request pipeline. support Event-based Asynchronous Pattern and reactive programming ,The service engine supports http, TCP, WS,Grpc, Thrift,Mqtt, UDP, and DNS protocols. It uses ZooKeeper and Consul as a registry, and integrates it. Hash, random, polling, Fair Polling as a load balancing algorithm, built-in service governance to ensure reliable RPC communication, the engine contains Diagnostic, link tracking for protocol and middleware calls, and integration SkyWalking Distributed APM
microsoft/dotnet-podcasts
.NET reference application shown at .NET Conf featuring ASP.NET Core, Blazor, .NET MAUI, Microservices, Orleans, Playwright, and more!
davidfowl/TodoApi
Todo application with ASP.NET Core Blazor WASM, Minimal APIs and Authentication
Version Downloads Last updated
1.6.9 15,316 9/26/2023
1.6.8 99,041 9/7/2023
1.6.7 39,389 9/1/2023
1.6.6 359,549 7/24/2023
1.6.5 321,642 6/19/2023
1.6.4 479,527 5/4/2023
1.6.4-preview4 4,179 4/17/2023
1.6.4-preview3 617 4/12/2023
1.6.4-preview2 7,096 4/11/2023
1.6.4-preview1 9,961 3/30/2023
1.6.3 929,206 3/7/2023
1.6.2 280,328 2/21/2023
1.6.1 153,696 2/13/2023
1.6.0 214,619 1/31/2023
1.5.0 228,614 1/17/2023
1.4.5 1,150,502 12/6/2022
1.4.4 278,737 11/21/2022
1.4.4-preview1 9,401 10/6/2022
1.4.3 7,282,502 9/26/2022
1.4.2 340,280 9/12/2022
1.4.1 78,104 9/7/2022
1.4.0 158,570 9/2/2022
1.4.0-preview3 422 9/2/2022
1.4.0-preview2 5,465 8/15/2022
1.4.0-preview1 4,345 8/1/2022
1.3.2 1,720,506 6/23/2022
1.3.1 11,150,038 4/13/2022
1.3.1-preview6 974 4/10/2022
1.3.1-preview5 14,019 3/3/2022
1.3.1-preview4 14,351 2/8/2022
1.3.1-preview3 700 2/3/2022
1.3.1-preview2 4,436 1/23/2022
1.3.1-preview 18,794 11/25/2021
1.3.0-preview 225,022 5/25/2021
1.2.3 270,720,179 8/29/2020
1.2.2 8,320,758 6/25/2020
1.2.1 1,811 6/24/2020
1.2.0 34,772 6/14/2020
1.2.0-preview.3 9,466 4/2/2020
1.2.0-preview.2 4,176 3/9/2020
1.2.0-preview 3,540 1/20/2020
1.1.4 77,243,419 9/15/2019
1.1.3 1,694,103 4/19/2019
1.1.2 1,123,531 12/13/2018
1.1.1 11,789,146 10/24/2018
1.1.0 79,331 8/16/2018
1.1.0-preview.4 1,273 7/18/2018
1.1.0-preview.3 5,879 6/14/2018
1.1.0-preview.2 852 6/7/2018
1.1.0-preview.1 820 5/25/2018
1.0.1 14,022 5/25/2018
1.0.0 22,609 5/8/2018
1.0.0-beta017 1,479 5/2/2018
1.0.0-beta016 2,404 4/8/2018
1.0.0-beta015 1,846 3/21/2018
1.0.0-beta014 4,457 2/13/2018
1.0.0-beta013 1,375 1/31/2018
1.0.0-beta012 1,681 1/24/2018
1.0.0-beta011 1,725 1/16/2018
1.0.0-beta010 1,366 1/11/2018
1.0.0-beta009 1,724 12/20/2017
1.0.0-beta008 1,524 12/14/2017