Using Swagger to automatically generate the client code

Swagger is a very powerful tool that I highly recommend to integrate into your API projects. It will simplify and speed-up both the development and QA processes. This tutorial is going to demonstrate that. Just keep reading.

For this tutorial I assume that you should have a basic understanding of ASP.NET Core Web API and Xamarin.Forms. If you want to follow this tutorial while checking the source code you are welcome to clone this tutorial’s repo.

In this post we will create a simple ASP.NET Core API with Swagger, we will generate the API consumer code using NSwag and finally we will integrate it to our Xamarin.Forms application.

Continue reading “Using Swagger to automatically generate the client code”

Advertisements

Adding swagger to ASP.NET Web.Api

Sounds easy right? But it turn to be very confusing. When I first tried to integrate Swashbuckle I met few problems:
  1. Auto generated documentation totally ignored existing and working API endpoints (methods in ApiControllers). So it was totally empty.
  2. After solving the first issue I realised that “/Token” endpoint is still not listed.
  3. Had to find a way to pass a bearer token with each request swagger generated for me.
So let’s start solving those problems one by one.
First we have to install Swashbuckle nuget package: Install-Package Swashbuckle
That should generate SwaggerConfig.cs under App_Start folder:

swashbuckle swagger
To solve problem #1 we need to use the right HttpConfiguration:
  1. Remove [assembly: PreApplicationStartMethod(typeof(SwaggerConfig), “Register”)] from SwaggerConfig.cs. We will register it manually. 
  2. Change the signature of Register method to public static void Register(HttpConfiguration httpConfig). This will allow us to pass the right HttpConfiguration.
  3. Change GlobalConfiguration.Configuration to httpConfig.EnableSwagger.  This will allow us to use the right HttpConfiguration upon the registration.
swashbuckle swagger

Now we have to manually register our swagger, for that we just have to add one additional line to Startup.cs;

At this point all our API endpoints should be visible if you navigate to http://yourapi:port/swagger
To solve problem number #2 we have to manually define documentation for our /Token endpoint by creating a AuthTokenDocumentFilter.cs (source):
public class AuthTokenDocumentFilter : IDocumentFilter
{
public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
{
swaggerDoc.paths.Add("/token", new PathItem
{
post = new Operation
{
tags = new List { "Auth" },
consumes = new List
{
"application/x-www-form-urlencoded"
},
parameters = new List {
new Parameter
{
type = "string",
name = "grant_type",
required = true,
@in = "formData",
@default = "password"
},
new Parameter
{
type = "string",
name = "username",
required = false,
@in = "formData"
},
new Parameter
{
type = "string",
name = "password",
required = false,
@in = "formData"
}
}
}
});
}
The next step will be to add AuthTokenDocumentFilter to our swagger configuration:

At this point “Auth” endpoint will become visible at http://yourapi:port/swagger

To solve problem number #3 we have to make few small changes in SwaggerConfig.cs.
Add the next line inside EnableSwagger section:

c.ApiKey("Token")
.Description("Bearer token")
.Name("Authorization")
.In("header");

Inside EnableSwaggerUi section add the next line:

c.EnableApiKeySupport("Authorization", "header");

Now in order to get a bearer token you can use swagger and if you want to use the retrieved token in all calls simply add it near the “Explore” button:

Good luck!

P.S.: You can get the file from GitHub Gist