Develop ASP.NET Core apps using OpenAPI tools

By Ryan Brandenburg

Microsoft.dotnet-openapi is a .NET Core Global Tool for managing OpenAPI references within a project.

Installation

To install Microsoft.dotnet-openapi, run the following command:

dotnet tool install -g Microsoft.dotnet-openapi

Add

Adding an OpenAPI reference using any of the commands on this page adds an <OpenApiReference /> element similar to the following to the .csproj file:

<OpenApiReference Include="openapi.json" />

The preceding reference is required for the app to call the generated client code.

Add File

Options

Short option Long option Description Example
-p --updateProject The project to operate on. dotnet openapi add file --updateProject .\Ref.csproj .\OpenAPI.json
-c --code-generator The code generator to apply to the reference. Options are NSwagCSharp and NSwagTypeScript. If --code-generator is not specified the tooling defaults to NSwagCSharp. dotnet openapi add file .\OpenApi.json --code-generator
-h --help Show help information dotnet openapi add file --help

Arguments

Argument Description Example
source-file The source to create a reference from. Must be an OpenAPI file. dotnet openapi add file .\OpenAPI.json

Add URL

Options

Short option Long option Description Example
-p --updateProject The project to operate on. dotnet openapi add url --updateProject .\Ref.csproj https://contoso.com/openapi.json
-o --output-file Where to place the local copy of the OpenAPI file. dotnet openapi add url https://contoso.com/openapi.json --output-file myclient.json
-c --code-generator The code generator to apply to the reference. Options are NSwagCSharp and NSwagTypeScript. dotnet openapi add file .\OpenApi.json --code-generator
-h --help Show help information dotnet openapi add url --help

Arguments

Argument Description Example
source-URL The source to create a reference from. Must be a URL. dotnet openapi add url https://contoso.com/openapi.json

Remove

Removes the OpenAPI reference matching the given filename from the .csproj file. When the OpenAPI reference is removed, clients won't be generated. Local .json and .yaml files are deleted.

Options

Short option Long option Description Example
-p --updateProject The project to operate on. dotnet openapi remove --updateProject .\Ref.csproj .\OpenAPI.json
-h --help Show help information dotnet openapi remove --help

Arguments

Argument Description Example
source-file The source to remove the reference to. dotnet openapi remove .\OpenAPI.json

Refresh

Refreshes the local version of a file that was downloaded using the latest content from the download URL.

Options

Short option Long option Description Example
-p --updateProject The project to operate on. dotnet openapi refresh --updateProject .\Ref.csproj https://contoso.com/openapi.json
-h --help Show help information dotnet openapi refresh --help

Arguments

Argument Description Example
source-URL The URL to refresh the reference from. dotnet openapi refresh https://contoso.com/openapi.json