ASP.NET Core: Simple shared DTOs (and Clients) with React
With the recent release of ASP.NET Core 5
, OpenAPI documents generation for describing our Web API is now included by default when we create a new Web API project.
This is definitely a great news as I always considered the addition of this feature (mainly by adding the Swashbuckle.AspNetCore
nuget package) as a “must have” for all Web API projects.
Now let’s not stop at documenting our Web API only, and let’s go one step further:
What if we could generate automatically some boilerplate code such as our DTOs
used in our APIs, and even better, generate our TypeScript
web Clients
automatically?
Well yes we can obviously as described in the official documention, but let me walk through you an example.
Start generating the code
As described in the documentation, many tools are at our disposal to generate our TypeScript
boilerplate code.
To start with, I highly recommend playing with the graphical tool NSwagStudio
Once installed, you can first define where is located your OpenAPI
document (or more historically called swagger
document):
And then configure your preferences of how your DTOs
and Clients
will be generated. Here is an example of the configuration I use:
As described in the previous articles, I use axios
Clients even though the generation is still in preview as described in the documentation.
I also set the Generation Mode
to MultipleClientsFromFirstTagAndOperationId
, which, by looking at the OpenAPI specification and how the Tag and the OperationId are generated, should produce 1 client per Controller
(by default) and 1 method by Endpoint
.
I also specify to produce DTOs
as TypeScript
interfaces and also an output file name that I will be able to use in my application.
Use the produced code in our app
This part should be pretty straightforward.
First, we can remove our manually written DTOs
in the useAxios
custom hook to use the DTOs
produced by nswag:
Then in our components, we will be able to use the generated strongly typed TypeScript Clients
And that’s all. Using APIs in the future should be much easier as the strongly typed TypeScript Clients
should guide us pretty well in calling correctly the APIs using the right URLs and parameters.
NSWAG Clients automated generation
Alright, another very complicated part. Now that we could check our process, let’s see how to update our generated Clients
, and of course, how to do it automatically
.
Fortunately, if you installed NSwagStudio
(using chocolatey for instance), the nswag.exe
command line tool is probably already installed and available in your PATH
, so the only things we need to do is to make sure that our nswag definition
is saved in a file called nswag.json
for instance:
Start our api (using dotnet run
for instance) and then we just need to execute the following command line:
nswag run /runtime:NetCore31
Note: NetCore31 being the default runtime selected when creating the
nswag.json
file.
And that’s all!
In conclusion
I hope this simple article gave you some hints about leveraging your OpenAPI
documentations and hopefully save some time creating and maintaining manually all of the DTOs
and Clients
.
While this scenario was ok for me as I wanted a kind of “update when you decide” scenario, having to start the API everytime you want to update your TypeScript Clients
might not be ideal and you might want to have a look to referencing directly the produced ASP.NET Core assemblies
instead of referencing the OpenAPI document
(more info in the Github documentation)
As usual, feel free to react in the comments or reply to me on Twitter @vivienfabing.
May the code be with you!