How to generate OpenApi Client SDK project in .Net Core

Question

Our customer has given us a swagger link for all of their API end-points. We have a .Net Core project using VS 2022 and .Net 6. Now we want to generate an OpenAPI client project to our same .Net Core solutions so that we will be calling the client's API end-point via the OpenAPI project.

The Steps I followed are:

• I downloaded the swagger json file from customer end point.
• I followed this document

As mentioned in that document, first, I installed Open API using this command

npm install @openapitools/openapi-generator-cli -g

Then, when I execute OpenAPI Generator CLI to generate our SDK with this command, I am getting the error 'Java' is not recognized as an internal or external command

openapi-generator generate -i swagger.json -g csharp-netcore -o Api.Client.Sdk --additional-properties packageName=Api.Client.Sdk

Answer 1

You should probably start from the ASP.NET Core docs on OpenAPI, to understand what OpenAPI is and what the various libraries do. OpenAPI isn't a library or custom protocol. It's a common way of specifying HTTP API endpoints and DTOs. You don't need to create anything special to call the HTTP APIs, just use HttpClient. A generator can be used to generate the DTOs for you from the OpenAPI link but is not necessary.

Swashbuckle is just one library that can be used to create Web API projects that provide an OpenAPI schema. It does this by generating a swagger.json document from your application's controllers and DTOs. You could create that document by hand if you wanted, but Swashbuckle is certainly easier to use.

You can use libraries like NSwag to generate boilerplate client code from an OpenAPI schema. One way is through the dotnet api tool, which generates a C# client and objects from a Swagger document.

You can install the tool with

dotnet tool install -g Microsoft.dotnet-openapi

And use it with dotnet openapi add url .... to configure your project to generate C# code at build time.

Let's say you create an empty console application with

dotnet new console

You can add generate a client based on the https://petstore3.swagger.io/ schema with

dotnet openapi add url https://petstore3.swagger.io/api/v3/openapi.json --help

This will add the NSwag.ApiDescription.Client NuGet package to the applition and an OpenApiReference tag pointing to the Schema document. This way the client can be refreshed when the schema changes.

The csproj file will look like this:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="12.0.2" />
    <PackageReference Include="NSwag.ApiDescription.Client" Version="13.0.5" />
  </ItemGroup>
  <ItemGroup>
    <OpenApiReference Include="openapi.json" SourceUrl="https://petstore3.swagger.io/api/v3/openapi.json" />
  </ItemGroup>
</Project>

The tool will also generate an openapiClient file and class inside the obj folder, which makes it available to the rest of the application. The client can now be used in Program.cs:

Console.WriteLine("Hello, World!");

var http = new HttpClient() { BaseAddress = new Uri("https://petstore3.swagger.io/") };

var client = new openapitest.openapiClient(http);
var results = await client.GetInventoryAsync();

Console.WriteLine(results);

The tool itself uses the NSwag library for code generation. There are other tools and applications that can generate C# code from an OpenAPI document.

Answer 2

For anyone wondering if there is an update to this answer, I looked at this Q+A and initially tried the fully integrated Connected Service OpenAPI generator in Visual Studio. The integration with the IDE is nice, but I thought the result could be better - it doesn't provide much customization, I prefer the System.Text.Json serializer instead of mixing serializers, and I think pre-generating a client and providing a mechanism for developer controlled updates is preferable.

Then I remembered watching this .NET Conf presentation on Kiota, a new OpenAPI Client generator created by a team at Microsoft:

https://www.youtube.com/watch?v=sQ9Pv-rQ1s8

I ended up deciding to use it, and I'm happy with the results. There is VS Code extension for it, and a 3rd party Visual Studio extension that includes it alongside other OpenAPI client generators. I didn't use either IDE plugin - I was happy using the CLI for creating the API client, and updating it.