Problem
Let’s start with an example to understand problem. Check the following code:
Above API is looking in swagger-ui like following:
As you can see, there is no information that 404 can return, even though method has a NotFound() method. We can only see info that we request to method with id that is not exist.
When we request to API with not existing product, it returns 404 with un documented warning.
Detect Problem: Analyzers
Analyzers work with controllers annotated with ApiController introduced in ASP.NET Core 2.1.0, while building on API conventions that is released in ASP.NET Core 2.2.0. To start using this, install the package:
Microsoft.AspNetCore.Mvc.Api.Analyzers
You should see this as warnings (squiggly lines) highlighting return types that aren’t documented as well as warnings in the output. In Visual Studio, this should additionally appear under the “Warnings” tab in the “Error List” dialog. You now have the opportunity to address these warnings using code fixes. Let’s look at the analyzer in action.
Before adding analyzer:
After adding analyzer:
The analyzer identified that the action returned a 404 but did not document it using a ProducesResponseTypeAttribute. It’s a great way to identify areas of your application that are lacking swagger documentation and correct it.
