Microsoft.OpenApi
1.6.19
Prefix Reserved
dotnet add package Microsoft.OpenApi --version 1.6.19
NuGet\Install-Package Microsoft.OpenApi -Version 1.6.19
<PackageReference Include="Microsoft.OpenApi" Version="1.6.19" />
paket add Microsoft.OpenApi --version 1.6.19
#r "nuget: Microsoft.OpenApi, 1.6.19"
// Install Microsoft.OpenApi as a Cake Addin #addin nuget:?package=Microsoft.OpenApi&version=1.6.19 // Install Microsoft.OpenApi as a Cake Tool #tool nuget:?package=Microsoft.OpenApi&version=1.6.19
OpenAPI.NET
Package | Nuget |
---|---|
Models and Writers | |
Readers | |
Hidi |
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
- Install core Nuget package Microsoft.OpenApi
- Install readers Nuget package Microsoft.OpenApi.Readers
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:
-
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:
- Clone the repo locally by running this command:
git clone https://github.com/microsoft/OpenAPI.NET.git
- Open the solution file
(.sln)
in the root of the project with Visual Studio - Navigate to the
src/Microsoft.OpenApi.Workbench
directory and set it as the startup project - 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">
- 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.
- Clone the repo locally by running this command:
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 | Versions 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. |
-
.NETStandard 2.0
- Microsoft.VisualStudio.Threading (>= 17.11.20)
NuGet packages (259)
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/abc2c7226ff616316cd1e05d76e6c36b49ce06a1 |
|
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 (43)
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
|
|
domaindrivendev/Swashbuckle.AspNetCore
Swagger tools for documenting API's built on ASP.NET Core
|
|
ChilliCream/graphql-platform
Welcome to the home of the Hot Chocolate GraphQL server for .NET, the Strawberry Shake GraphQL client for .NET and Banana Cake Pop the awesome Monaco based GraphQL IDE.
|
Version | Downloads | Last updated | |
---|---|---|---|
1.6.19 | 7,509 | 8/30/2024 | |
1.6.18 | 30,429 | 8/23/2024 | |
1.6.17 | 120,861 | 8/6/2024 | |
1.6.16 | 78,412 | 7/30/2024 | |
1.6.15 | 405,302 | 6/18/2024 | |
1.6.14 | 15,854,182 | 3/6/2024 | |
1.6.13 | 1,209,073 | 1/29/2024 | |
1.6.12 | 458,838 | 1/16/2024 | |
1.6.11 | 2,205,321 | 11/22/2023 | |
1.6.10 | 704,675 | 10/30/2023 | |
1.6.9 | 627,925 | 9/26/2023 | |
1.6.8 | 313,583 | 9/7/2023 | |
1.6.7 | 114,142 | 9/1/2023 | |
1.6.6 | 1,159,160 | 7/24/2023 | |
1.6.5 | 723,878 | 6/19/2023 | |
1.6.4 | 906,429 | 5/4/2023 | |
1.6.4-preview4 | 13,346 | 4/17/2023 | |
1.6.4-preview3 | 1,636 | 4/12/2023 | |
1.6.4-preview2 | 9,697 | 4/11/2023 | |
1.6.4-preview1 | 19,188 | 3/30/2023 | |
1.6.3 | 1,592,949 | 3/7/2023 | |
1.6.2 | 473,558 | 2/21/2023 | |
1.6.1 | 229,687 | 2/13/2023 | |
1.6.0 | 321,819 | 1/31/2023 | |
1.5.0 | 310,785 | 1/17/2023 | |
1.4.5 | 2,251,304 | 12/6/2022 | |
1.4.4 | 442,649 | 11/21/2022 | |
1.4.4-preview1 | 14,400 | 10/6/2022 | |
1.4.3 | 30,855,213 | 9/26/2022 | |
1.4.2 | 450,722 | 9/12/2022 | |
1.4.1 | 101,005 | 9/7/2022 | |
1.4.0 | 245,719 | 9/2/2022 | |
1.4.0-preview3 | 1,516 | 9/2/2022 | |
1.4.0-preview2 | 13,869 | 8/15/2022 | |
1.4.0-preview1 | 6,865 | 8/1/2022 | |
1.3.2 | 2,317,843 | 6/23/2022 | |
1.3.1 | 23,945,308 | 4/13/2022 | |
1.3.1-preview6 | 2,081 | 4/10/2022 | |
1.3.1-preview5 | 15,666 | 3/3/2022 | |
1.3.1-preview4 | 26,188 | 2/8/2022 | |
1.3.1-preview3 | 1,835 | 2/3/2022 | |
1.3.1-preview2 | 6,071 | 1/23/2022 | |
1.3.1-preview | 25,342 | 11/25/2021 | |
1.3.0-preview | 270,168 | 5/25/2021 | |
1.2.3 | 429,798,476 | 8/29/2020 | |
1.2.2 | 9,771,037 | 6/25/2020 | |
1.2.1 | 2,950 | 6/24/2020 | |
1.2.0 | 41,347 | 6/14/2020 | |
1.2.0-preview.3 | 13,705 | 4/2/2020 | |
1.2.0-preview.2 | 4,303 | 3/9/2020 | |
1.2.0-preview | 4,653 | 1/20/2020 | |
1.1.4 | 86,199,768 | 9/15/2019 | |
1.1.3 | 1,865,260 | 4/19/2019 | |
1.1.2 | 1,268,745 | 12/13/2018 | |
1.1.1 | 12,671,337 | 10/24/2018 | |
1.1.0 | 85,252 | 8/16/2018 | |
1.1.0-preview.4 | 1,390 | 7/18/2018 | |
1.1.0-preview.3 | 5,996 | 6/14/2018 | |
1.1.0-preview.2 | 960 | 6/7/2018 | |
1.1.0-preview.1 | 925 | 5/25/2018 | |
1.0.1 | 18,225 | 5/25/2018 | |
1.0.0 | 35,107 | 5/8/2018 | |
1.0.0-beta017 | 2,554 | 5/2/2018 | |
1.0.0-beta016 | 3,394 | 4/8/2018 | |
1.0.0-beta015 | 2,910 | 3/21/2018 | |
1.0.0-beta014 | 5,575 | 2/13/2018 | |
1.0.0-beta013 | 2,453 | 1/31/2018 | |
1.0.0-beta012 | 2,923 | 1/24/2018 | |
1.0.0-beta011 | 2,810 | 1/16/2018 | |
1.0.0-beta010 | 2,419 | 1/11/2018 | |
1.0.0-beta009 | 2,743 | 12/20/2017 | |
1.0.0-beta008 | 2,583 | 12/14/2017 |