Versioning WebApi and documenting version with Swagger

Versioning in WebApi

Note: This post draws alot of points from https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/ – but is more about implementation and documentation through swagger.
So please go read Troy’s post and then come back :).
There are a couple of ways of versioning a restful api
among them are:
1. Url versioning e.g. GET http://example.com/api/v1/cars
2. Request-Header e.g. GET http://example.com/api/cars — Header: api-version: 1
There are pros and cons in both regards, Troy gets around them quite nicely.
Time to code!

Url Versioning

Easy – simply use either the RoutePrefix- or RouteAttribute

Read more about the Routing-Attribute here

Request-Header

Drawing from Troy’s post
We create a new attribute which uses a custom routing constraint

** Usage **

Effectively matching routes based on the “api-version” header.

Swagger

When using swashbuckle (swagger implementation for .Net).
It knows about the default Route- and RoutePrefixAttribute, so Url Versioning is taken care of, out of the box.
But Header versioning is not.
Fortunately, it’s quite easy to implement an OperationFilter that adds the header as a parameter to the endpoints in question.
This implementation uses a list of versions and the endpoints relativepaths to know when to add the parameter and when not to.


How would you implement the OperationFilter?

Documenting roles with swashbuckle

How to document attribute usage with swagger

You could basically document any attribute you have decorated your actions with, but this will focus mainly on documenting the role part of the Authorize attribute.
When using roles based authentication I like to document the roles in my swagger spec, this gives a nice indication, to the consumer, of which roles are required for different endpoints.
Here I have a basic Authorize attribute with a required role of “Admin”.

As with most other things swashbuckle related, we need to create an IOperationFilter

And that is it, you have now auto documented every role required across your API.
The swagger docs will look like the following.
BackupPortal_API

Throttling actions in WebApi using AttributeFilter

I recently had to come up with a solution to throttle an action in an API i’ve written.
First thing I did was to see what others had used (No reason to invent the wheel right?).
I came across this stackoverflow answer – which is basically what I will use in this blog post (mostly for a reminder to myself I guess).
Full credits go to Jarrod Dixon

The Attribute

The Annotation

Since it’s an attribute, we just annote it to an action
The attribute takes a unique name, amount of seconds and the message to return.
If the action is run more often than allowed, the action will return 409 - conflict

Remove 'Try it out!' buttons from Swagger-ui

This is a quick way of removing the ‘try it out’ buttons from specific operation types, when using Swagger-ui for documentation

This will be a short one.
When using Swashbuckle to create documentation, you might want to remove the Try it out buttons, maybe all of them, or maybe just the ones on Put on Post operations
Well I’ve created a small script that is injected into swagger-ui through the SwaggerConfig.cs
The following script will remove the TryItOut buttons from all Put and Post operations.

The script is injected through the SwaggerConfig.cs like so

Remember that the .js file needs to be an Embedded Resource else it won’t work.

Adding basic authentication to swashbuckle

Note: This is applies to swashbuckle 5.2.2 and below, will update post for 5.4.0.


On my recent endeavors, I’ve had the pleasure of getting to use “Swagger”, yes it is as swag as it sounds…
Swagger for .Net is thankfully packaged by a guy I only know as “DomainDriven” on github.
The .Net version is called “Swashbuckle”.
I will not go in to adding swashbuckle to your project, the README pretty much says it all.
Lets get back to basic-auth.
According to the swashbuckle docs, to add Basic-Auth to swashbuckle, you need to add the following in the SwaggerConfig.cs file

This adds the “SecurityDefinition” as per the swagger spec.
The SwashBuckler docs finishes the security segment with

NOTE: These only define the schemes and need to be coupled with a corresponding “security” property at the document or operation level to indicate which schemes are required for each operation. To do this, you’ll need to implement a custom IDocumentFilter and/or IOperationFilter to set these properties according to your specific authorization implementation

Which is what I’ll be showing you how to do.

Onwards!

Lets start with the UI.
To remove the APIKey input and replace that with a nice username/password input pair, we need to inject a new index.html.
Note: You can see the base swagger index file here
You can see the entire index.html below
[/learn_more]
What I’ve changed from the original index.html is actually not a whole lot.
I’ve removed everything that had to do with the apikey input and instead added new username and password inputs;
Now all there needs to be done is to inject the new index file into swagger-ui

Now that we have the UI in order, we move on to the actual spec implementation.
To actually live up to the swagger spec, we are still missing the Security Requirement Object on the operations.
According to the spec;

Security Requirement Object
Lists the required security schemes to execute this operation. The object can have multiple security schemes declared in it which are all required (that is, there is a logical AND between the schemes).
The name used for each property MUST correspond to a security scheme declared in the Security Definitions.

Which basically means that we need to add "security": [{"basic": []}] to all of our operations.
This only applies to the code generated by swagger, but how do we implement this through Swashbuckle?
We need to create a class that inherits from the IOperationFilter interface.
And then add the security scheme to all operation.
The security theme is basically just a “basic : []” applied under the security configuration (speaking in pure swagger spec terms).

Now we just need to apply the OperationsFilter in the SwaggerConfig

and that is it, now the “basic” security scheme will be applied to all operations.