Creating C# client library for Web API projects (Part 1)

Peter Jausovec
Sep 17, 2017 · 4 min read

In this article I’ll show you how to quickly create a C# client library for a Web API project using Swagger, Swashbuckle and autorest. I am using the awesome VS Code and .NET Core 2.0 for my sample Web API project, but you could easily do the same using Visual Studio and a different version of .NET. You can get the sample code (in multiple branches) from https://github.com/peterj/swaggerPlayground/. Starting point is the Empty-Project branch.

One note in case you decide to use a different .NET version — make sure you install the right Swashbuckle NuGet package as there’s one for .NET Core and another one for other .NET versions.

Also, here are the prerequisites in case you want to follow along:

Once you’re set (you installed all prerequisites and you have a starting project), you’re ready to go!

Add Swashbuckle

Simply put, Swashbuckle knows how to generate a Swagger spec for a Web API. From the Swagger spec we will later use Autorest to create our client libraries.

Swashbuckle can be added as a NuGet package to the project by running this command:

dotnet add package Swashbuckle.AspNetCore

Now we can hookup it out to our project and have it generate the Swagger file for us automatically.

Configure Swashbuckle

Basic configuration for Swashbuckle is fairly straight forward and

  • Add the following line to the ConfigureServices method in the Startup class (Startup.cs) to register the Swagger generator and define a Swagger document.
services.AddSwaggerGen(o => {
o.SwaggerDoc(
"v1",
new Info
{
Title = "swaggerPlayground API",
Version = "v1"
});
});
  • Enable the middleware where the generated Swagger document will be server. To do this, add the following lines to the Configure method:
app.UseSwagger();
app.UseSwaggerUI(o =>
{
o.SwaggerEndpoint("/swagger/v1/swagger.json", "API");
});

At this point, you can run your app (⌘+F5) and navigate to: http://localhost:5000/swagger/v1/swagger.json. You should get something that’s similar to the figure below.

swagger.json endpoint in the browser

This is a Swagger spec and it’s needed to generate a client library for our REST API. Make sure you save this file as we are going to need it next (or switch to Configure-Swashbuckle branch in the sample repo).

Enter Autorest

Once we have the Swagger spec, autorest comes into play. Autorest is a tool for generating client libraries using a spec file that describes the REST API. In our case, the spec is the generated swagger.json file.

Using autorest, you can generate the client libraries for the following languages:

  • C#
  • NodeJS
  • Python
  • Java
  • Ruby
  • Go

We are going to take the swagger.json file and create a C# client library. To do so, we need to provide autorest the input file, output folder and the language we want to generate the client library in. For example:

autorest --input-file=swagger.json --output-folder=generated_csharp --csharp

Similarly, we could generate a client library for any other language, by replacing --csharp with e.g. --python or --go or any other supported language.

With the above command, autorest generated 3 code files in /generated_csharp folder:

  • ISwaggerPlaygroundAPI.cs
  • SwaggerPlaygroundAPI.cs
  • SwaggerPlaygroundAPIExtensions.cs

Building the generated C# client library

Unfortunately, autorest doesn’t generate a .csproj file (yet), so we need to do that on our own. In the /generated_csharp folder create a new file named SwaggerPlaygroundAPI.csproj and paste in the following:

<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<PackageId>SwaggerPlaygroundAPI</PackageId>
<Description>SwaggerPlaygroundAPI Library</Description>
<AssemblyName>SwaggerPlaygroundAPI</AssemblyName> <TargetFrameworks>netcoreapp2.0</TargetFrameworks>
</PropertyGroup>
</Project>

Note: I am using netcoreapp2.0 target framework in the file, but you could replace that with other framework version(s).

Now we need to add a couple of more packages to that project and we will be good to go:

dotnet add package Microsoft.AspNetCore
dotnet add package Microsoft.Rest.ClientRuntime
dotnet add package Newtonsoft.Json

At this point you can build the client SDK by running dotnet build and the build process will produce a SwaggerPlaygroundAPI.dll The source code with generated C# client library is in the Create-Client-Library branch.

In order to use consume this library from .NET Core 2.0, we will have to create NuGet package in the next post.

Conclusion

The above walkthrough is probably the fastest and simplest way to generate a client library, however it’s far from ideal. Here are some of the things that I’ll address in the next post(s):

  • We have 2 controllers in our Web API — it would be awesome if the generated library was separated based on the controllers. E.g. NumbersAPI and ValuesAPI instead of having one huge class for all API methods.
  • API method naming is ugly: ApiNumbersGetWithHttpMessagesAsync. Having names like GetNumbers or GetValues would be way better.
  • How to protect the API with an API key?

Peter Jausovec

Written by

— Kubernetes — Docker — Go — Python — React —

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade