Efficient User

In the past post, we discussed the Web Improvements that have been released in the ASP.NET Core 2.2 preview. We have discussed how the creation, testing, and documentation of API has been improved in the ASP.NET Core release. Using Swagger gen, we created API documentation and also able to test our API application from the UI itself. On successful HTTP action, we usually get 200 status code and response from the API.

ASP.NET Core provides custom error response by default from 2.2 release. The error response includes TraceId to correlate to other response easily,

In the earlier post, we use SwashBuckle to generate swagger UI, but it isn’t able to determine all the possible response type of an HTTP method. For example, a post method can return 200, 400, 500 kinds of responses based on different input. Our documentation should cover most of the possible response type available in our API.

[ProducesResponseType(StatusCodes.Status400BadRequest)]

We shall specify the possible response type of each method in our Controller which will generate related documentation in the Swagger UI. But it will be a tedious process to analyze and add all the methods in our API. For this, ASP.NET Core 2.2 shipped an API Analyzer that will analyze the API actions and provide code fix that can be added in the code. We shall the package “Microsoft.AspNetCore.Mvc.Api.Analyzers” from Nuget Package manager

Once added API analyzer in our project, the analyzer starts showing the possible response type suggestion in warning window.

Instead of providing mentioning each response type on every action, we shall globally enable the API convention type with default conventions like below

[assembly: ApiConventionType(typeof(DefaultApiConventions))]
namespace APITest.Controllers
{
  ....
}

These DefaultApiConventions can also be extended and defined separately based on our needs. DefaultApiConventions covers some basic commonly used convention types in APIs. Based API conventions, now the swagger UI generates documentation of various response types and its sample inputs.

Documentation and testing become simpler in ASP.Net Core 2.2. Please try out for your API code, and leave your feedback in comment section. Happy Coding!