Microsoft.OpenApi.OData 2.0.0-preview.7

Prefix Reserved
This is a prerelease version of Microsoft.OpenApi.OData.
dotnet add package Microsoft.OpenApi.OData --version 2.0.0-preview.7                
NuGet\Install-Package Microsoft.OpenApi.OData -Version 2.0.0-preview.7                
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.OData" Version="2.0.0-preview.7" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Microsoft.OpenApi.OData --version 2.0.0-preview.7                
#r "nuget: Microsoft.OpenApi.OData, 2.0.0-preview.7"                
#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.OData as a Cake Addin
#addin nuget:?package=Microsoft.OpenApi.OData&version=2.0.0-preview.7&prerelease

// Install Microsoft.OpenApi.OData as a Cake Tool
#tool nuget:?package=Microsoft.OpenApi.OData&version=2.0.0-preview.7&prerelease                

nuget

Convert OData to OpenAPI.NET

Introduction

The Microsoft.OpenAPI.OData.Reader library helps represent an OData service metadata as an OpenApi description. It converts OData CSDL, the XML representation of the Entity Data Model (EDM) describing an OData service into Open API based on OpenAPI.NET object model.

The conversion is based on the mapping doc from OASIS OData OpenAPI v1.0 and uses the following :

  1. Capabilities vocabulary annotation
  2. Authorization vocabulary annotation
  3. Core vocabulary annotation
  4. Navigation property path
  5. Edm operation and operation import path

Overview

The image below is generic overview of how this library can convert the EDM model to an OpenAPI.NET document object.

Convert OData CSDL to OpenAPI

For more information on the CSDL and Entity Data model, please refer to http://www.odata.org/documentation. For more information about the Open API object of model, please refer to http://github.com/microsoft/OpenAPI.NET

Sample code

The following sample code illustrates the use of the library

public static void GenerateOpenApiDescription()
{
    IEdmModel model = GetEdmModel();
    OpenApiDocument document = model.ConvertToOpenApi();
    var outputJSON = document.SerializeAsJson(OpenApiSpecVersion.OpenApi3_0);
    var outputYAML = document.SerializeAsYaml(OpenApiSpecVersion.OpenApi3_0);
}

public static IEdmModel GetEdmModel()
{
    // load EDM model here...
}

Or with the convert settings:

public static void GenerateOpenApiDescription()
{
    IEdmModel model = GetEdmModel();
    OpenApiConvertSettings settings = new OpenApiConvertSettings
    {
        // configuration
    };
    OpenApiDocument document = model.ConvertToOpenApi(settings);
    var outputJSON = document.SerializeAsJson(OpenApiSpecVersion.OpenApi3_0);
    var outputYAML = document.SerializeAsYaml(OpenApiSpecVersion.OpenApi3_0);
}

public static IEdmModel GetEdmModel()
{
    // load EDM model here...
}

The GetEdmModel() method can load a model in 3 ways:

  1. Create the Edm model from scratch. For details refer building a basic model

  2. Load the Edm model from CSDL file. The following shows a code sample that loads a model from a csdl file.

    public static IEdmModel GetEdmModel()
    {
        string csdlFilePath = @"c:\csdl.xml";
        string csdl = System.IO.File.ReadAllText(csdlFilePath);
        IEdmModel model = CsdlReader.Parse(XElement.Parse(csdl).CreateReader());
        return model;
    }
    
  3. Create the Edm model using Web API OData model builder. For details refer to the web api model builder article

Nuget packages

The OpenAPI.OData.reader nuget package is at: https://www.nuget.org/packages/Microsoft.OpenApi.OData/


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.

You can also open an issue directly on this repo via this link.

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.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (6)

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

Package Downloads
DT-ESA.Elevate.SecureConnectors

Generates DTO classes and provides wrappers for resource access.

Swashbuckle.AspNetCore.Community.OData

Provides support for Microsoft.AspNetCore.OData in Swashbuckle

Microsoft.Restier.AspNetCore.Swagger

Package Description

DT-ESA.SecureConnectors

Generates DTO classes and provides wrappers for resource access.

ITP.Helpers

Helper library for ITP

GitHub repositories (4)

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

Repository Stars
microsoft/OpenAPI.NET
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.
OData/RESTier
A turn-key library for building RESTful services
OData/AspNetCoreOData
ASP.NET Core OData: A server library built upon ODataLib and ASP.NET Core
unchase/Unchase.OpenAPI.Connectedservice
:scroll: Visual Studio extension to generate OpenAPI (Swagger) web service reference.
Version Downloads Last updated
2.0.0-preview.7 840 10/28/2024
2.0.0-preview.6 388 10/17/2024
2.0.0-preview.5 154 10/11/2024
2.0.0-preview.4 105 10/10/2024
2.0.0-preview.3 348 10/3/2024
2.0.0-preview.2 905 8/23/2024
2.0.0-preview.1 95 8/16/2024
1.6.8 25,361 7/24/2024
1.6.7 6,467 6/26/2024
1.6.6 6,613 6/11/2024
1.6.5 3,280 5/27/2024
1.6.4 2,283 5/21/2024
1.6.3 3,307 4/29/2024
1.6.2 1,125 4/26/2024
1.6.1 7,472 3/28/2024
1.6.0 7,546 3/18/2024
1.6.0-preview.10 488 3/4/2024
1.6.0-preview.9 118 3/1/2024
1.6.0-preview.8 151 2/13/2024
1.6.0-preview.7 281 2/5/2024
1.6.0-preview.6 66 2/2/2024
1.6.0-preview.5 89 2/1/2024
1.6.0-preview.4 176 1/25/2024
1.6.0-preview.3 92 1/23/2024
1.6.0-preview.2 187 1/16/2024
1.6.0-preview.1 74 1/9/2024
1.5.0 34,715 12/8/2023
1.5.0-preview9 2,035 11/13/2023
1.5.0-preview8 425 11/6/2023
1.5.0-preview7 716 10/26/2023
1.5.0-preview6 232 10/24/2023
1.5.0-preview5 669 10/4/2023
1.5.0-preview4 1,032 9/5/2023
1.5.0-preview3 335 9/1/2023
1.5.0-preview2 943 6/14/2023
1.5.0-preview1 334 6/2/2023
1.4.0 112,670 5/3/2023
1.4.0-preview7 324 5/2/2023
1.4.0-preview6 349 4/27/2023
1.4.0-preview5 818 4/20/2023
1.4.0-preview4 284 4/18/2023
1.4.0-preview3 413 4/17/2023
1.4.0-preview2 876 4/13/2023
1.4.0-preview1 539 4/5/2023
1.3.0 11,313 3/29/2023
1.3.0-preview4 497 3/22/2023
1.3.0-preview3 425 3/21/2023
1.3.0-preview2 888 2/28/2023
1.3.0-preview1 386 2/1/2023
1.2.0 27,028 1/20/2023
1.2.0-preview9 2,291 12/15/2022
1.2.0-preview8 1,027 11/17/2022
1.2.0-preview7 462 11/8/2022
1.2.0-preview6 958 11/1/2022
1.2.0-preview5 506 10/24/2022
1.2.0-preview4 736 10/6/2022
1.2.0-preview3 353 10/3/2022
1.2.0-preview2 377 9/28/2022
1.2.0-preview1 343 9/28/2022
1.1.0 56,011 9/14/2022
1.0.11 32,303 7/18/2022
1.0.11-preview5 653 7/8/2022
1.0.11-preview4 554 7/6/2022
1.0.11-preview3 1,163 6/22/2022
1.0.11-preview2 770 6/6/2022
1.0.11-preview1 399 5/30/2022
1.0.10 18,889 5/10/2022
1.0.10-preview3 1,261 3/29/2022
1.0.10-preview2 1,156 3/3/2022
1.0.10-preview1 592 2/25/2022
1.0.9 72,655 10/7/2021
1.0.8 83,442 5/6/2021
1.0.7 16,441 4/13/2021
1.0.6 25,365 2/11/2021
1.0.5 1,183 2/6/2021
1.0.4 51,144 7/21/2020
1.0.2 7,676 5/25/2020
1.0.1 41,878 10/10/2019
1.0.0 2,188 9/25/2019
1.0.0-beta9 14,903 8/13/2019
1.0.0-beta8 2,915 8/6/2019
1.0.0-beta7 5,584 9/24/2018
1.0.0-beta6 1,042 9/19/2018
1.0.0-beta5 989 9/7/2018
1.0.0-beta4 1,349 5/30/2018

- Upgraded to Microsoft.Odata.Edm 8.0.0
- Cleaned up obsolete APIs
- Changed target framework to net8.0
- Adds support for retrieving collection of enum values from UpdateMethod property of UpdateRestrictions annotation #564
- Adds nullable to double schema conversions #581
- Updates tag names for actions/functions operations #585
- Creates unique operation ids for paths with composable overloaded functions #580
- Further fixes for double/decimal/float schema conversions #581
- Replaced integer types by number types
- Further fix for generating unique operation ids for paths with composable overloaded functions where all functions in path are overloaded #594
- Further fix for generating unique operation ids for navigation property paths with composable overloaded functions #596
- Updates PUT operation id prefix from Update to Set #600