"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.
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).
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:
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.
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".
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.
In the next code snippet we can see a simple XML documentation for our Get endpoint from the API.
In order to open the json document, where your documentation is included, access the link on the top of the dashboard.
Json documentation can be seen in the next image.
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!