Skip to content

Document your Microservice with Swagger

Swagger is an open-source toolset that can be easily integrated into your solution and which helps you to document and test your APIs. It is so simple that even none technical people can use it. In my last post, I created two Microservices and today I will explain how I integrated Swagger.

What is Swagger?

Swagger is an open-source toolset from Smartbear and is based on the OpenAPI specificiation. For .net core, you can install Swagger easily as Nuget package and configure it in the Startup class of your solution. In simple words, Swagger wraps the XML comments of your API in a nice looking functional GUI which shows your the available actions and models and also lets you send requests to the actions. You can even attach authentication objects like a JWT.

Install Swagger

You can find the code of  the finished demo on GitHub.

To implement Swagger, I installed the Swashbuckle.AspNetCore NuGet package in the API project. Next, I added the path to the XML file which contains all the XML comments of the actions and models in the ConfigureServices method in the Startup class.

Configure Swagger to read the XML file with the comments of your API
Configure Swagger to read the XML file with the comments of your API

The next step is to tell ASP .net core to use Swagger and its UI. You can  add both in the Configure method of the Startup class. Additionally, I configured Swagger to load the the GUI when starting your solution.

Enable Swagger and SwaggerUI
Enable Swagger and SwaggerUI

That’s all you have to configure in Swagger. Now I only have to make two adjustments to the starting project. First, I tell the project to create the XML file by opening the properties of the project. Go to the Build tab and check XML documentation file. It is important that you use All Configurations as Configuration in the dropdown on top All Configurations.

Create the XML documentation file
Create the XML documentation file

After you configured your project to create the XML documentation file, you will get warnings that an XML comment is missing on top of your actions. I find these warnings pretty annoying, so I suppress them by adding 1591 in the text box for Suppress warnings in the Build tab (see screenshot above).

The last step is to remove the launch URL from the launchSettings.json file. You can just remove the line, otherwise, the Swagger GUI won’t be loaded when the application is started and you have to call its URL.

That’s all you have to do to set up Swagger. Before I test it, I will add some XML comments to the actions, attributes to my model and some more configuration.

Adding XML comments to API Actions

The XML comment on an action describes what the action does, what the parameters are, what it returns and what return codes it can produce. Usually, I have the opinion that the name of the method and parameter should describe themselves but in this case, we need a comment for the Swagger GUI. To create an XML comment write three / on top of an action. This will give you the template of the comment.

Additionally, I add the response codes and the ProducesResponseType attribute which will help users of the GUI to understand what return codes can be expected from the API.

Adding an XML comment to the API
Adding an XML comment to the API

Adding Attributes to the Model

The Swagger UI for .net core also includes the models of your application. The UI shows which models are available, what properties they have including their data type and their attributes, e.g. if the property is required. To use this feature, you only have to add the attribute to the property of your models. Swagger creates everything out of the box by itself.

Adding attributes to the model
Adding attributes to the model

Personalize the Swagger UI

Swagger is also easily extensible. You can load your own CSS, or change the headline or information displayed on top of the page. For now, I will add my contact information so developers or customers can contact me if they have a problem. To add your contact information use the SwaggerDoc extension and pass an OpenApiInfo object inside the AddSwaggerGen extension in the Startup class.

Adding contact information to the Swagger UI
Adding contact information to the Swagger UI

Testing Swagger

Everything is set up and when you start the application, you should see the Swagger UI.

Swagger UI
Swagger UI

On top of the page, you can see my headline and my contact information. Then you can see my two actions, even in different colors for the different HTTP verbs they use and then you can see my models. Next to the post action, you can see the XML comment I added to describe the method. The put action doesn’t have an XML comment yet, therefore no text is displayed.

When you click on an action, it opens and shows you information about the parameter, and also shows the responses which I added previously in the XML comment.

Swagger UI information about an action
Swagger UI information about an action

When you click on the Try it out button in the top right corner, Swagger will already create a request for you with all parameters. You can edit them and then send the request to the server and the UI will show you the reply.

Testing an action of the API
Testing an action of the API

After clicking on Try it out, you can define the format of your request on the top right. I leave the default application/json and also leave the created model as it is. When you click on Execute, the response and also the sent request and the request URL will be shown below. In my case, the response is a code 200 and a Customer JSON object. On the bottom right is a button where you can even download the result. This might be useful if you have a test document and want to attach the result to it.

Conclusion

Today, I talked about Swagger, one of my favorite NuGet packages. Swagger can be used to document and test your application and make this information easily accessible even for none technical people. Swagger is also very easy to set up and can be extended and modify to fit your needs.

You can find the code of  the finished demo on GitHub. In my next post, I will explain the implementation of CQRS and how it can be used to split up your read and write operations.

Published inASP.NET MVC / CoreProgrammingTools

Be First to Comment

    Leave a Reply

    Your email address will not be published. Required fields are marked *

    RSS
    Follow by Email
    LinkedIn
    Share