Document your API with Swagger

On this article you can find a short presentation of Swagger UI and a simple way in which you can easily document your ASP .NET Web API by using this tool.
By Dorin Puscas Posted 27 October 2016

Document your API with Swagger

"If it is not documented, it doesn't exist. As long as information is retained in someone's head, it is vulnerable to loss." said Louis Fried in 1992, my birth year.

That is absolutely valid when we talk about APIs, because any small-to-complex API needs to be documented, in order to make it easy to use. This might be an interesting challenge, because you have to find the bridge between the abstract world of computer programming and the way people think and work. Here is where Swagger shows its great utility.

The purpose of this article is to introduce Swagger and its benefits and also to present the way in which you can easily document your API by using this tool.

Being a collection of HTML, Javascript and CSS assets, Swagger makes the API exist by generating a pretty nice documentation and sandbox from a Swagger-compliant API. As any programmer would be more than happy to receive a detailed, clear and easy-to-follow documentation, Swagger offers an excellent API documentation which is generated directly from the source code, being all the time up-to-date. Also, Swagger offers a nice dashboard that allows the interaction with the described API. This dashboard can be used not only to understand the API, but also to make real calls to your endpoints, which can have a major role on testing your API.

Swagger is language agnostic, so anybody can use it, regardless the programming language. On this article the focus will be on documenting an ASP.NET Web API.

First of all, you need an ASP.NET Web API Project. For this example, I created a simple controller (SwaggerDemoV1Controller) with basic operations methods (Get, Post, Put, Delete).

Considering that you have all the endpoints implemented, and your API is "up and running", everything is done, but something seems missing... as Louis Fried said, your API does not exist until it is documented. So let's make it exist!

The first step in configuring Swagger is to install the Swashbuckle NuGet Package (the latest stable version at the moment is 5.4.0, released on 11th of August 2016).

Install Swagger

The Swashbuckle Package installation also creates a bootstrapper file (App_Start/SwaggerConfig.cs) which initiates Swashbuckle on the application start-up. Now you just need to set up Swagger:

Swagger Config File

After the basic set up is made, the dashboard will become available. You can access it by opening your API url on the browser and then navigate to [yourApiUrl]/swagger/ui/index.

Swagger in browser

Using this dashboard, besides the fact that you have a presentation of all your API methods, including their parameters and details, you can make real calls to your API. The only thing that you need to do is to complete your request from this dashboard and to press 'Try It Out' button. This will make a real call to your API with the parameters and the request body that you have inserted before. Swagger can be also used for secured APIs, which requires authorization, but these things are a bit more complex and they are not the scope of this article.

After that, if you want to change your code, your methods, to add or remove controllers or anything else, Swagger will be permanently synchronized with your code.

Another useful feature of Swagger is to create a json document with the entire documentation of the API endpoints and models. To enrich this, you should enable XML documentation, by right clicking on the Web API project -> "Properties" - choose "Build", and on "Output" section check "XML documentation file" check box and set the file path to: "bin[YourWebAPIProjectName].XML".

Enable XML Documentation

It is truly recommended to write useful XML documentation comments to your API controller methods and models, in order to make your life easier and also to create an easy-to-follow documentation. To add these comments to your Swagger documentation, you need to configure it, on "SwaggerConfig.cs", as shown in the picture below.

SwaggerConfig.cs

In the next code snippet we can see a simple XML documentation for our Get endpoint from the API.

Simple XML documentation

In order to open the json document, where your documentation is included, access the link on the top of the dashboard.

Documentation available in the browser

Json documentation can be seen in the next image.

Json documentation in browser

In the end, you have an API which is documented and offers a nice experience to developers. You should keep in mind that this process of documenting APIs should start at the very beginning of the development process, for it to be easy to maintain.

In conclusion, after you developed your API, you can understand that Swagger is a powerful tool for API documentation. It can be easily understood by developers and non-technical people such as Product Managers, Business Analysts and even stakeholders, and it has a strong community with lots of helpful contributors.

Moreover, the provided dashboard is a great tool to understand and test your API. The most meaningful feature of this tool is that it keeps the API documentation up to date. Being language agnostic, it can be used by anyone, so let's make APIs exist!

Dorin Puscas
Dorin Puscas
.NET Developer