These days, APIs are everywhere. Be it internal APIs (APIs within the system) or external ones (exposed across systems), APIs are the base which enable huge systems to be scalable and maintainable. Dealing with such vast APIs and understanding its various methods can be daunting for a developer. This is where Swagger (also called Open API) can be useful.
So, what exactly is Swagger?
At its heart, Swagger is a language-agnostic specification for describing REST APIs.
Swagger has some advantages,
- It helps to better understand capabilities of a service without any direct access to the implementation.
- Helps minimize the amount of work needed to connect disassociated services.
- Reduces the amount of time needed to accurately document a service.
As part of this walkthrough, we’ll focus on using the Swashbuckle.AspNetCore open source implementation for generating Swagger documents for ASP.Net Core Web Apis.
How Swagger really works?
The core to the Swagger specification is the document named
swagger.json and is generated by the Swagger implementation. It describes the capabilities of the API and how to access it using HTTP.
The toolchain also comes with a Swagger UI, which basically uses the json document and displays it in a web-based UI.
Adding the Swagger implementation to Asp.Net Web APIs
For this walkthrough we’ll quickly bootstrap a Asp.Net Web API project that comes out of the box with .Net Core and add Swagger to it.
1. Create a Asp.Net Web API project
Lets create the Asp.Net Web API project
This project has a single controller -
We can host the project using
dotnet run and try accessing the API
http://localhost:<random_port>/api/values from the browser.
This would show the json output as
Now, this was a very basic API implementation with a simple response. However, in actual projects you can have very complex APIs requiring multiple parameter inputs and a complex Json response.
2. Add Swagger to the Web API project
Lets now add the Swagger toolchain to this project and check how it makes it easier to deal with APIs. To do this, we’ll have to install the nuget package Swashbuckle.AspNetCore This package has 3 main components
A Swagger object model and middleware to expose SwaggerDocument objects as JSON endpoints
A Swagger generator that builds SwaggerDocument objects directly from your routes, controllers, and models
A Swagger UI tool which interprets Swagger JSON to build a rich, customizable experience for describing the Web API functionality. It includes built-in test harnesses for the public methods.
We can install the package using
3. Configuring the Swagger middleware
Now that the package is installed, we can add and configure the Swagger middleware.
We can now launch the app and navigate to
This will provide the Swagger specification endpoints.
The same can be viewed via Swagger UI at
You can click on the individual APIs and click on the Try it out button to actually provide input parameters and run the API.
4. Add details to the Swagger document
Further to this, we can use the
AddSwaggerGen method to add information such as author, license and description.
This will show up in the Swagger UI as …
That’s it!! We have our Web APIs up and running with Swagger documentation support.
You may clone a working version of this project from my GitHub Repository here.
There are some additional configurations that can be done to improvise the Swagger support further. I’ll take these up in a separate post.
Hope this was useful!!