Create dotnet Core WebApi with Swagger

What is Swagger?

Swagger is an awesome framework that offers a systematic way of notating the interface of any RESTful service under the OpenAPI specification. This is a simplified definition which might not mean much until you know what OpenAPI specification really means.

What is OpenAPI specification?

According the wikipedia page, it was originally known as the Swagger Specification. It is a machine readable interface file used for describing, producing, consuming and visualising RESTful web services.

Okay so what?

This enables developers to create their new service APIs in dotnet core or any backend technology and then generate interactive web pages that help clients of their API to visualise what the API looks like. The generated visualisation allows a client to execute HTTP requests with sample json (or whatever the contract is).

So how do I use Swagger in my dotnet core project?

Welcome Swashbuckle.

Excuse me. You said Swagger earlier!!!

What on earth is Swashbuckle?

Swashbuckle allows you to seamlessly add swagger to your .NET Web Api projects.

So can I not use swagger directly in my dotnet core?

As of today, at least I do not know of another way to use swagger in a .net project.

Okay, tell me then how to use swagger in my dotnet core project?

Install the Swashbuckle.AspNetCore nuget package into your dotnet core WebApi project. Then follow instructions from the Swashbuckle: Getting Started Page

So let us say your API's default url was http://localhost:5000/ then you should be able to access the swagger UI page if you type in http://localhost:5000/swagger.

That looks nice. What about XML Docs?

Now if you wanted to add more, like XML documentation, just add XML doc comments to your API end points using the funky

/// <summary>
/// my comment
/// </summary>

And if you like to add a file generated from it, then right click your dotnet core api project and open the properties window. In the Build tab under the Output section, check the XML Documentation checkbox and then provide a file name.

Is that all?

Yes. To generate a swagger UI page, that is all that is required.

What about autogenerated API Client code?

For that you need to use a tool called NSwag.

What's wrong with you? Why are you obsessed with Swag?

No. It isn't me. It is just that these projects are named like that. NSwag is the Swagger toolchain for .NET, Web API and typescript.

What a crazy world we live in! So what is this thing?

NSwag, is a tool that cleverly generates a client in C# or Typescript for your API's swagger open api specification. The swagger JSON file that was generated while you configured Swashbuckle is consumed by NSWag to generate a client. That is the power of the OpenAPI specification. Very handy when you start working on several services, like in a micro-services architecture.

Shut up and take my money! But wait instructions please

So to use NSwag on windows, just download the NSwagStudio application or follow instructions from the NSwagStudio Wiki page. It has even got screenshots! But to add it to your dotnet core webapi projects follow the instructions for dotnet core

• Open NSwagStudio
• In the input section of the Documents tab, choose Swagger specification
• In the swagger specification URL field, paste your application's swagger json's url. which should look something like this: https://localhost:5001/swagger/v1/swagger.json
• Assuming that you are here to generate a CSharp client, in the Outputs section, check the CSharp Client.
• In the newly appeared CSharp Client tab's Settings tab, give a meaningful Namespace name and if you wish to generate Contracts, then give the same or a specific relative namespace there too. You could just view the output by clicking Generate Outputs button below.
• If you want to generate the client files into a folder, scroll down to the Output section in the CSharp Client tab.
• Give appropriate file names for the Client file and the contracts file. I generally follow the convention WebApi.Client.Generated.cs and WebApi.Contract.Generated.cs. Then click generate files and the files should be generated for you!

What if I wanted to use the generated files in a nuget package or something?

Good question. Most developers share their WebApi clients as nuget packages that can then be installed in which ever project they want to use.

• Create a dotnet core classlib project. You can do this easily using the command line. Just type dotnet new classlib
• Now that you have this new project, go to your NSwag Studio's CSharp Client setting's Output section and set the output path to the directory where you just created the dotnet class library.
• If you created the class library in /c/code/WebApiSwaggerClient then the output file paths should be c:\code\WebApiSwaggerClient\WebApi.Client.Generated.cs and c:\code\WebApiSwaggerClient\WebApi.Contract.Generated.cs
• Then click Generate Files button.
• Now you should be able to see the newly generated files in your class library project. For this example, let us assume the project name is WebApiSwaggerClient
• Try building the project dotnet build. Your first attempt would fail as the autogenerated code relies on NewtonsoftJson package.
• Install the package - dotnet add package Newtonsoft.json
• Build again - dotnet build
• Now package it - dotnet pack -c Release -o . /p:PackageVersion=1.0.0
• You should now get a new NuGet package!! Publish it to your local NuGet repository.
• nuget push -source YourNugetRepoName -ApiKey Blah WebApiSwaggerClient.1.0.0
• Alright! That's it, you got your share-able nuget package in your package repository!

Wow! So cool! But simple!

Happy coding.