This is my fourth post in the Series: Enumeration classes – DDD and beyond. If you are new to the Enumeration class, I suggest going through my previous posts.
- Part 1: Introduction to Enumeration Classes
- Part 2: Enumeration class and JSON Serialization
- Part 3: Enumeration class as query string parameter
- Part 4: Generating client code with NSwag for Enumeration class (this post)
What is NSwag?
From the NSwag GitHub documentation:
NSwag is a Swagger/OpenAPI 2.0 and 3.0 toolchain for .NET, .NET Core, Web API, ASP.NET Core, TypeScript (jQuery, AngularJS, Angular 2+, Aurelia, KnockoutJS and more) and other platforms, written in C#. The OpenAPI/Swagger specification uses JSON and JSON Schema to describe a RESTful web API. The NSwag project provides tools to generate OpenAPI specifications from existing ASP.NET Web API controllers and client code from these OpenAPI specifications.
If you are new to NSwag, Microsoft documentation here will come handy. Also, please have a look at youtube video created by my former colleague and friend,Rahul, where he has described how to use NSwag and NSwagStudio in detail.
The sample API
Let us go back to our old PaymentType Enumeration class.
Consider a simple HttpPost endpoint, which accepts a Transaction object in the body.
As you can see in the above code, Transaction DTO has a property PaymentType..
NSwag does not support System.Text.Json at the time of this writing. As a result, we need to fallback to our trustworthy old friend NewtonsoftJson. We will configure the API to use NewtonsoftJson and add EnumerationJsonConverter, as explained in Part 2 of this series.
Testing Api on Postman
The Postman request accepts the PaymentType as both as name and value, just like a normal EnumType.
Adding Swagger to Api
To generate client code from NSwag, let us first add Swagger support to our API.
The swagger page of our application would look similar to below.
Notice that the PaymentType schema is as a complex object instead of an Enum type.
To fix this, we need to extend our OpenAPI specification by creating a new SchemaFilter that renders an Enumeration class as an Enum type in Swagger.
Next, we need to add EnumerationToEnumSchemaFilter to the SwaggerGen options in Startup.cs.
If we run our application now, the PaymentType schema is an Enum type.
Generating client code from NSwagger Studio
Now, we let us generate the client using NSwagger studio. We need to specify the path to swagger.json and click Generate Outputs. Note the schema for PaymentType in OpenAPI specification. It is of an Enum type just like on the Swagger page.
The generated C# client also creates an Enum type.
This post explains how we can render an Enumeration class as an Enum type in our client code generated through NSwag. I hope this series has given a complete picture of how we can replace Enumeration class at various parts of our system, including but not limited to web Api, persistence, and Domain-Driven-Design.