The code in this post is build using VS2015 and AspNetCore RC1

Recently we have been looking at Swagger as a way to generate a meta data endpoint for our Web Api’s. You can easily do this by adding the Swashbuckle NuGet packages to you solution.

Setting up Swashbuckle

You start by adding the following packages to your package.json:

1
2
"Swashbuckle.SwaggerGen": "6.0.0-rc1-final"
"Swashbuckle.SwaggerUi": "6.0.0-rc1-final"

You then add the following code

1
2
3
4
5
6
7
8
9
10
services.AddSwaggerGen();
services.ConfigureSwaggerDocument(options =>
{
options.SingleApiVersion(new Info
{
Version = "v1",
Title = "Blog Test Api",
Description = "A test API for this blogpost"
});
});

to your ConfigureServices method inside Startup.cs file. Then you add the following lines

1
2
app.UseSwaggerGen()
app.UseSwaggerUi();

to your Configure method inside Startup.cs. After compiling and running the application you can go to your api url /swagger/ui to get a page looking like this.
Swagger UI
The test page even enables you to do quick testing of your API. Everything looks fine right? Well, this works if your Web Api is accessible without credentials. When you have a Web Api that only accept JWT Bearer tokens for example the standard page is useless unless you disable your authorization.

Luckily the Swashbuckle package has a way to add custom fields to the Swagger user interface.

OperationFilters

You start by creating a class which implements the interface called IOperationFilter. Then you have to implement the Apply method with your custom logic. In our case the method looks like this.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
public void Apply(Operation operation, OperationFilterContext context)
{
var filterPipeline = context.ApiDescription.ActionDescriptor.FilterDescriptors;
var isAuthorized = filterPipeline.Select(filterInfo => filterInfo.Filter).Any(filter => filter is AuthorizeFilter);
var allowAnonymous = filterPipeline.Select(filterInfo => filterInfo.Filter).Any(filter => filter is IAllowAnonymousFilter);

if (isAuthorized && !allowAnonymous)
{
if (operation.Parameters == null)
operation.Parameters = new List<IParameter>();

operation.Parameters.Add(new NonBodyParameter
{
Name = "Authorization",
In = "header",
Description = "access token",
Required = true,
Type = "string"
});
}
}

In our case we add a NonBodyParameter to the set of parameters within the generated user interface. After implementing the OperationFilter the only thing left is letting Swashbuckle know the OperationFilter exists. You do that by adding the following statement to the ConfigureServices part of Startup.cs.

1
options.OperationFilter(new AuthorizationHeaderParameterOperationFilter());

The total Swashbuckle configuration then looks like

1
2
3
4
5
6
7
8
9
10
11
services.AddSwaggerGen();
services.ConfigureSwaggerDocument(options =>
{
options.SingleApiVersion(new Info
{
Version = "v1",
Title = "Blog Test Api",
Description = "A test API for this blogpost"
});
options.OperationFilter(new AuthorizationHeaderParameterOperationFilter());
});

If you then go to the Swagger UI page you will notice there is a new field added to the generated Swagger UI methods.
Swagger UI with Authorization field

Conclusion

And there you have it. An easy way to extend the default Swashbuckle generated UI with new fields that are necessary to quickly test your Web Api’s successfully.