If customize word is confusing you, you need to take a look our first article about adding swagger into ASP .Net Core 2.1 Web API.
Add Swagger to ASP.NET Core 2.1 Web API
Testing an API is a challenge and it depends of various third party tools to test an API. But swagger make the life…
In the current article, we will talk more about customization of swagger once you will install the basic swagger in ASP .Net Core 2.1 Web API.
We are familiar with XML comments for documentation but swagger does not show XML comments by default. This option is available to show XML comments on swagger UI. We need to make sure that when we build our project, the comments are getting saved into an XML file. Swagger will use the XML file to show comments on swagger UI.
To make the XML file, right click on project in Visual Studio and then go to properties. Navigate to build tab and check “XML documentation file” option in output section.
In the value field for “XML documentation file” option, you need to specify complete path for your XML file like:
The value in “Output path” should be like:
Now save the settings and Add a method in Startup.cs to get the path of generated XML. This code to get the XML path will work in your local environment as well as in the production environment.
Next, add code to include XML comments in ConfigureService method. Like:
Next, add XML comments to our actions. Here is XML comment for Delete method.
Now run the app, you should see XML comments.
You can display enum values in sawagger UI using DescribeAllEnumsAsStrings metod like:
The story does not stop here, you need to do a little more. Add an enum in the project like:
and then pass a parameter of the enum type into an endpoint like:
Now run the project again, you will see the enum values in your endpoint details like:
There is also a method named “DescribeStringEnumsInCamelCase” to convert enum string values in camel case.
Swagger Documentation For Each API Version
If you have multiple versions of your WEB API, then you can use swagger to generate the different document based on the selected version. Like:
Run the project again, you will see an option for version 2 in top right drop down in swagger UI like:
There is still more to cover for versioning of API but, for now try to understand and practice this first. Later will be discuss more about versioning of API in future articles.