Getting Started with Swagger API

Years ago, we had something called ASMX web services. While I wouldn’t want to go back to those, they did have some advantages over the current way many APIs are created. Back in the ASMX days, you got a pretty well-defined contract for interacting with web services. Today if someone is setting up a Web API Controller, there is no documentation for the API. With many modern web services, the first thing you do is craft a test harness so you can test the web service. That was also something the old ASMX did better than the current Web API land.

Enter Swagger. It solves those two problems. First, it creates some documentation on how to consume your web services. Second, it creates pages that you can use to test your web service.

First, create a .NET Core WebAPI web application.

Swagger API - Don't Panic Labs

Swagger API - Don't Panic Labs

Add Swashbuckle.AspNetCore NuGet package to our project by right-clicking on your project and selecting “Manage Nuget Packages”. Then search for Swashbuckle.AspNetCore.

Swagger API - Don't Panic Labs

Update program.cs to have add Swagger:

Now run the project, and go to localhost:port/swagger to see the Swagger site running.

Swagger API - Don't Panic Labs

Now that we have a running Swagger site running, let’s dive a little deeper. We are going to create a super simple API that does addition. Not the most useful API in the world, but good enough for our example. We’ll start by creating a new controller named MathController.

Swagger API - Don't Panic Labs

Let’s write a super complex method on our Math controller. Let’s call it “Add”. 🙂

Now we can run the app in Visual Studio again, and we will again go to http://localhost:63034/swagger/.

This will give us a nice web interface to test our method.

Swagger API - Don't Panic Labs

Swagger is pretty amazing, and it gives you a pretty quick and easy way to document our APIs. It also gives you a quick and easy way to test your API.

Next time you are building an API for your web application, give Swagger a try.

Related posts