April 18, 2019

Documenting your RESTful C# ASP.Net Core Web Api using Swashbuckle & Swagger

RESTful Api Endpoints

How often have you been in a situation where you’re having to code against an undocumented API? Perhaps your team is building an API and publishing it to another group of developers. Understanding the API endpoints without the correct documentation can be a challenge…

C# ASP.Net Core Web Api - Swashbuckle Swagger

C# ASP.Net Core Web Api - Swashbuckle Swagger

Enter “Swagger”…

Swagger enables you o generate interactive documentation as a readable representation of a RESTful API.

In order to generate Swagger documents for our C# ASP.Net Core Web Api application, we need to utilise Swashbuckle - An open source project.

C# ASP.Net Core Web Api - Swashbuckle Swagger

C# ASP.Net Core Web Api - Swashbuckle Swagger

Let’s Code…

I’ve implemented a basic C# ASP.Net Core Web Api solution with 2 public endpoints for us to document.

C# ASP.Net Core Web Api - Swashbuckle Swagger

C# ASP.Net Core Web Api - Swashbuckle Swagger

Now to pull in the required Swashbuckle packages from Nuget.

C# ASP.Net Core Web Api - Swashbuckle Swagger

C# ASP.Net Core Web Api - Swashbuckle Swagger

Now to add our configuration into the appsettings file.

C# ASP.Net Core Web Api - Swashbuckle Swagger

C# ASP.Net Core Web Api - Swashbuckle Swagger

Head to your Startup.cs file and let’s configure our Swagger middleware. Our previously added configuration details can now be made use of.

C# ASP.Net Core Web Api - Swashbuckle Swagger

C# ASP.Net Core Web Api - Swashbuckle Swagger

Now to make use of the variables and configure our Swagger service.

C# ASP.Net Core Web Api - Swashbuckle Swagger

C# ASP.Net Core Web Api - Swashbuckle Swagger

We can now configure our Swagger endpoint.

C# ASP.Net Core Web Api - Swashbuckle Swagger

C# ASP.Net Core Web Api - Swashbuckle Swagger

Finally let’s head to the endpoint URL -

C# ASP.Net Core Web Api - Swashbuckle Swagger

C# ASP.Net Core Web Api - Swashbuckle Swagger

…and here’s the result!

C# ASP.Net Core Web Api - Swashbuckle Swagger

C# ASP.Net Core Web Api - Swashbuckle Swagger

Enjoy!