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
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
And then configure your preferences of how your
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
I also specify to produce
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
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
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
And that’s all!
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
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!