Generate a TypeScript client from .NET 6 Web API

.NET 6 is a cross-platform, open-source framework developed by Microsoft for building modern applications. One of its key features is the ability to build Web APIs that can be consumed by clients written in a variety of languages and platforms.

OpenAPI (formerly known as Swagger) is a specification for building RESTful APIs. It provides a standardized way to describe the structure of API endpoints and the data they produce and consume.

TypeScript is a statically typed superset of JavaScript that adds optional type annotations, classes, interfaces, and other features to JavaScript. It is a popular choice for building client-side web applications.

With the OpenAPI TypeScript Client Generator, you can generate TypeScript classes and interfaces that correspond to the API endpoints described in your OpenAPI specification. This makes it easy to consume your Web API from a TypeScript client.

Generate a TypeScript client from your .NET 6 Web API

To generate a TypeScript client from your .NET 6 Web API, you can follow these steps:

Step 1: Install the NSwag tool

To generate a TypeScript client from your .NET 6 Web API, you will need to install the NSwag tool. You can do this using the following command in the Package Manager Console:

Install-Package NSwag.AspNetCore

Step 2: Add an OpenAPI specification file to your Web API project

To generate the TypeScript client, you will need to provide an OpenAPI specification file that describes your Web API. You can generate this file automatically by adding the Swashbuckle.AspNetCore NuGet package to your Web API project and configuring it in your Startup.cs file.

Install-Package Swashbuckle.AspNetCore

In your Startup.cs file, configure the Swashbuckle middleware to generate the OpenAPI specification file by adding the following code to the ConfigureServices method:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});

Step 3: Configure NSwag in your Web API project

Once you have generated the OpenAPI specification file, you will need to configure NSwag to use it to generate the TypeScript client. You can do this by adding the following code to the ConfigureServices method in your Startup.cs file:

services.AddOpenApiDocument();

This code configures NSwag to generate the OpenAPI specification file using the Swagger UI middleware, and to include the TypeScript client generator in the output.

Step 4: Generate the TypeScript client

With the NSwag middleware configured, you can now generate the TypeScript client using the following command in the Package Manager Console:

nswag openapi2tsclient /input:bin\Debug\net6.0\MyAPI.OpenApi.json /output:Client.ts

Replace bin\Debug\net6.0\MyAPI.OpenApi.json with the path to your OpenAPI specification file, and Client.ts with the path where you want to generate the TypeScript code.

Once the command completes, you should see a TypeScript file generated that includes classes and interfaces corresponding to the API endpoints in your Web API.

Step 5: Consume the TypeScript client in your client application

With the TypeScript client generated, you can now use it to consume your Web API from a TypeScript client. Here's an example of how you might use the generated TypeScript client in a simple React app:

import { ApiClient } from './Client';

const client = new ApiClient();

async function fetchData() {
  const response = await client.getWeatherForecast();
  const data = await response.json();
  console.log(data);
}

fetchData();

This code imports the ApiClient class from the generated TypeScript client, creates a new instance of the ApiClient, and uses it to call the getWeatherForecast endpoint. The response is then parsed as JSON and logged to the console.

Overall, the NSwag tool makes generating a TypeScript client from your .NET 6 Web API easy, providing a standardized way to consume your API from a client written in TypeScript.

Conclusion

Generating a TypeScript client from your .NET 6 Web API using the NSwag tool provides several benefits. It provides a standardized way to consume your API from a client written in TypeScript, reducing the amount of manual work required to create a client application. It also ensures that the TypeScript client is always in sync with your Web API, as any changes made to the API will be reflected in the generated client code.

Overall, generating a TypeScript client from your .NET 6 Web API using the NSwag tool is a powerful technique that can help streamline the development process and improve your client applications' overall quality and consistency.