SWAGGER IN .NET
Enhance Swagger Documentation with Annotations in ASP.NET core
With default integration of swagger with ASP.Net core Webapi, we just get basic UI without any description for API. but wouldn’t it be useful to provide some description about the API and Schema.
In this tutorial, we are going to explore different ways of providing the description to API and Schema.
We will also explore how to provide good example values.
Let’s get started..
Project Creation
Create a project using following command.
dotnet new webapi -o DemoSwaggerAnnotationBuild and run to make sure no errors.
Let’s see how we can enhance the documentation.
Using XML Document
This is most simple and known ways of documenting the API’s.
Swashbuckle library can make use of the generated Xml Documentation and create the appropriate swagger document out of it.
Let’s take a look at the example.
Project settings
First we need to make required project settings. we have to enable generation of xml documentation. and also provide appropriate name for file. See below picture for reference
You might start seeing the warning “1591” for missing xml comments, so you can suppress this warning.
Program.cs
Next we need to add the configuration like below.
I am using .NET 6. if you are using any version <6.0, then this code will go into Startup.cs.
Controller
In the controller we will provide the xml document for API’s
Model
We provide xml documentation in model classes also so that appropriate example can be shown.
Now with these changes we are ready to run. Hit the F5 and run the app.
Swagger UI
As you can see in the above pictures that description and examples are taken from xml documentation and placed appropriately.
Using Swashbuckle Annotation
Now we will look at the another way of achieving same. if you don’t want to generate the xml document file then we can use Swashbuckle Annotation library to provide more details about API.
We will start with clean project.[Undo everything we did previously or create a new project]
And add the reference
dotnet add package Swashbuckle.AspNetCore.Annotations Program.cs
We will start by making changes in swagger configuration.
Controller
Model
Let’s run the app.
We can see the description, but we don’t see the examples.
I did some search and found that Swashbuckle.AspNetCore.Annotations does not provide a way to give example.
But we can enhance our own.
Let’s add a class “SwaggerSchemaExampleAttribute”. which will be use to define value for attribute.
Now we need to schema filter class “SwaggerSchemaExampleFilter”
Here we are adding the example to the schema where this attribute is defined.
Now let’s add example to Model
and add the schema filter to configuration.
Let’s run the app.
Now we can see the examples also.
We can enhance other properties also if they are not provided by this library.
You can find the source code at GitHub
Summary
In this tutorial, we have two ways in which we can enhance Swagger API documentation.
You can use which ever you like. I don’t see any particular pros or cons of either one.
Hope you enjoyed reading the article.
Happy coding and Keep learning..!
My other swagger related blogs.
