Оффлайн
- Регистрация
- 1 Мар 2015
- Сообщения
- 1,481
- Баллы
- 155
A step-by-step guide on how to automatically create strongly typed TypeScript client for your .NET API service.
Creating Demo API
First, let's demonstrate how to create an API. All examples are provided using console utilities, but they can be reproduced using IDE of choice.
Let's create a solution for our application:
dotnet new sln - name OpenApiDemo
Creating a full-scale WebAPI project with controllers:
dotnet new webapi -use-controllers -n DemoApi
And let's add it to our solution:
dotnet sln add DemoApi
As a result, you will have file structure like this:
Adding OpenAPI and Scalar
Recently, Microsoft introduced their own API description generator, reducing the reliance on Swashbuckle Swagger. Although this decision generated some controversy, considering the recent commercialization of many free libraries such as MassTransit and AutoMapper, it may not be entirely unfavorable. It's 2025 after all, so no need to depend on swagger.
So, let's add an OpenApi package to our dotnet project:
dotnet add DemoApi package Microsoft.AspNetCore.OpenApi
And also let's add Scalar to test our API (it's not actually needed to create typescript client, but it's always nice to have).
dotnet add DemoApi package Scalar.AspNetCore
And, also, we need to setup scalar to communicate with openapi generated references:
builder.Services.AddControllers();
// Learn more about configuring OpenAPI at
builder.Services.AddOpenApi();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
app.MapScalarApiReference();
}
Let's run our API and see if everything is OK:
dotnet run --project DemoApi
Generating OpenAPI reference file on build
Fine! Now we need to get api description file on build. To do this we need to install Microsoft.Extensions.ApiDescription.Server package by following command:
dotnet add DemoApi package Microsoft.Extensions.ApiDescription.Server
Ok, let's build project
dotnet build DemoApi
After building there should be a file DemoApi.json inside obj folder of your project
Regrettably, the DemoApi.json file is generated exclusively within the obj folder. For those utilizing a CI/CD pipeline where the backend and frontend are built in separate steps, and the output from the backend build is limited to the bin folder or, in some cases, only the docker image.
There are two potential solutions: either copy this file during the CI/CD step or modify your .csproj file accordingly. Given that MSBuild can be complex, here is the code that needs to be added:
<Target Name="PostBuild" AfterTargets="Build">
<Copy SourceFiles="$(ProjectDir)obj\DemoAPI.json" DestinationFolder="$(OutDir)" />
<Message Text="open api file copiied to $(OutDir)" Importance="high"/>
</Target>
<Target Name="CopyFilesToPublish" AfterTargets="Publish">
<Copy SourceFiles="$(OutDir)\DemoAPI.json" DestinationFolder="$(PublishDir)"/>
</Target>
Command to test those adjustments:
dotnet publish DemoApi -o out
Front-end
Front-end Preparations:
We will be using orval to generate our client, primarily because it comes highly recommended by my front-end coworkers.
Some preparational steps:
mkdir Front
cd Front
npm init
npm i orval -D
npm i axios
TypeScript client generation:
Create orval.config.js (this one generates client that uses axios library to make calls. If you want to use fetch api see documentation):
module.exports = {
weather: {
input: {
target: "../out/DemoAPI.json",
},
output: {
mode: "split",
target: "endpoint.ts",
schemas: "model",
},
},
};
To generate your typescript client, use command:
node .\node_modules\orval\dist\bin\orval.js --config .\orval.config.js
That's it. Your typescript client file is in endpoint.ts, and types for API contract calls are in models folder.
If you need a source code for this tutorial, I had created a github .
Btw, you can subscribe to my , to get my posts faster.
Creating Demo API
First, let's demonstrate how to create an API. All examples are provided using console utilities, but they can be reproduced using IDE of choice.
Let's create a solution for our application:
dotnet new sln - name OpenApiDemo
Creating a full-scale WebAPI project with controllers:
dotnet new webapi -use-controllers -n DemoApi
And let's add it to our solution:
dotnet sln add DemoApi
As a result, you will have file structure like this:
Adding OpenAPI and Scalar
Recently, Microsoft introduced their own API description generator, reducing the reliance on Swashbuckle Swagger. Although this decision generated some controversy, considering the recent commercialization of many free libraries such as MassTransit and AutoMapper, it may not be entirely unfavorable. It's 2025 after all, so no need to depend on swagger.
So, let's add an OpenApi package to our dotnet project:
dotnet add DemoApi package Microsoft.AspNetCore.OpenApi
And also let's add Scalar to test our API (it's not actually needed to create typescript client, but it's always nice to have).
dotnet add DemoApi package Scalar.AspNetCore
And, also, we need to setup scalar to communicate with openapi generated references:
builder.Services.AddControllers();
// Learn more about configuring OpenAPI at
builder.Services.AddOpenApi();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
app.MapScalarApiReference();
}
Let's run our API and see if everything is OK:
dotnet run --project DemoApi
Generating OpenAPI reference file on build
Fine! Now we need to get api description file on build. To do this we need to install Microsoft.Extensions.ApiDescription.Server package by following command:
dotnet add DemoApi package Microsoft.Extensions.ApiDescription.Server
Ok, let's build project
dotnet build DemoApi
After building there should be a file DemoApi.json inside obj folder of your project
Regrettably, the DemoApi.json file is generated exclusively within the obj folder. For those utilizing a CI/CD pipeline where the backend and frontend are built in separate steps, and the output from the backend build is limited to the bin folder or, in some cases, only the docker image.
There are two potential solutions: either copy this file during the CI/CD step or modify your .csproj file accordingly. Given that MSBuild can be complex, here is the code that needs to be added:
<Target Name="PostBuild" AfterTargets="Build">
<Copy SourceFiles="$(ProjectDir)obj\DemoAPI.json" DestinationFolder="$(OutDir)" />
<Message Text="open api file copiied to $(OutDir)" Importance="high"/>
</Target>
<Target Name="CopyFilesToPublish" AfterTargets="Publish">
<Copy SourceFiles="$(OutDir)\DemoAPI.json" DestinationFolder="$(PublishDir)"/>
</Target>
Command to test those adjustments:
dotnet publish DemoApi -o out
Front-end
Front-end Preparations:
We will be using orval to generate our client, primarily because it comes highly recommended by my front-end coworkers.
Some preparational steps:
mkdir Front
cd Front
npm init
npm i orval -D
npm i axios
TypeScript client generation:
Create orval.config.js (this one generates client that uses axios library to make calls. If you want to use fetch api see documentation):
module.exports = {
weather: {
input: {
target: "../out/DemoAPI.json",
},
output: {
mode: "split",
target: "endpoint.ts",
schemas: "model",
},
},
};
To generate your typescript client, use command:
node .\node_modules\orval\dist\bin\orval.js --config .\orval.config.js
That's it. Your typescript client file is in endpoint.ts, and types for API contract calls are in models folder.
If you need a source code for this tutorial, I had created a github .
Btw, you can subscribe to my , to get my posts faster.