Building Typescript client from Swagger/OpenAPI

Building Typescript client from Swagger/OpenAPI

Table of Contents

1. Introduction
2. What is Swagger?
3. Using NSwag to Generate a Typescript Client
   • Installation
   • Setting up the Application
   • Running the DB Migrator
   • Launching the Application
   • Accessing the Swagger Endpoint
4. Issues with Default Swagger Endpoint
   • Problem with Generic Type List
   • Ambiguous Request Names
5. Fixing the Issues
   • Installing Custom Extensions
   • Updating Custom Schema and Operation
   • Rerunning the Application
6. Using OpenAPI Typescript Generator
   • Downloading Swagger JSON
   • Running OpenAPI Command
   • Exploring the Generated Files
7. Conclusion

Introduction

In this article, we will explore how to generate a typescript client from a Swagger or OpenAPI endpoint using NSwag or other open-source libraries. We will discuss the steps involved in setting up the application, accessing the Swagger endpoint, and resolving any issues that may arise during the generation process. Additionally, we will also explore an alternative approach using the OpenAPI Typescript Generator.

What is Swagger?

Swagger, now known as the OpenAPI Specification, is a specification for documenting RESTful APIs. It provides a standardized way to describe the structure and functionality of an API, including endpoints, request/response formats, and authentication methods. Swagger allows developers to generate client SDKs, server stubs, and documentation automatically based on the API specification.

Using NSwag to Generate a Typescript Client

Installation

To begin, we need to install NSwag, a popular tool for generating client code from Swagger or OpenAPI specifications. The installation process is straightforward; all you need to do is run the following command:

npm install -g nswag

Once NSwag is installed, we can proceed with setting up our application.

Setting up the Application

For demonstration purposes, let's assume we are using an application called ABP. ABP comes with an inbuilt Swagger endpoint, making it an ideal choice for this example. Let's create a new ABP application by following these steps:

1. Create an empty folder for your application.
2. Copy and paste the ABP app command, making sure you have the ABP CLI installed.
3. Open the application in your preferred code editor, such as VS Code.

Running the DB Migrator

Before we launch the application, we need to run the DB migrator to set up the database and perform any necessary migrations. To do this, execute the following command:

dotnet run /seed

This command will create the application and set up the required configurations automatically.

Launching the Application

With the DB migrator successfully executed, we can now proceed to launch our ABP project. The application will run on a specified port; in this case, it is running on port 4386. To launch the application, run the following command:

dotnet run

Once the application is running, we can now access the Swagger endpoint.

Accessing the Swagger Endpoint

Now that the application is launched, we can access the Swagger endpoint to view the available endpoints and their corresponding JSON representation. To access the Swagger endpoint, open your browser and navigate to the following URL:

http://localhost:4386/swagger/index.html

This will open the Swagger UI, where you can explore the available endpoints and interact with the API.

Issues with Default Swagger Endpoint

While the default Swagger endpoint provides a convenient way to view and interact with the API, it may have some limitations and issues that need to be addressed before generating a typescript client code. Let's discuss two common issues that can arise:

Problem with Generic Type List

One of the issues that can occur when generating typescript client code from a default Swagger endpoint is with generic type lists. The default Swagger implementation may not properly list generic type information, resulting in improperly generated typescript class names. This can lead to confusion and ambiguity in the generated code.

Ambiguous Request Names

Another issue that can arise is the presence of ambiguous request names. When generating typescript client code based on the default Swagger endpoint, you may come across methods with generic names like "get" or "search." These names lack specificity, making it difficult to understand their purpose. This ambiguity can lead to confusion and hinder the development process.

Fixing the Issues

To address the aforementioned issues, we will explore two solutions: using custom extensions and updating the custom schema and operation.

Installing Custom Extensions

First, we need to add custom extensions to our project. These extensions will help generate friendly IDs for schema and operation names. You can find the necessary code for these extensions in the Swashbuckle.WebApi package. Copy the code from the Swashbuckle.Core package and add it to your project's extensions folder.

Updating Custom Schema and Operation

Next, we need to update the custom schema and operation to utilize the friendly IDs generated by the extensions. This ensures each endpoint and request has a unique and descriptive name, eliminating any ambiguity or confusion. By using the controller and action names, we can create operation IDs that accurately represent the purpose of each method.

After making these updates, restart your application and access the Swagger endpoint again. You will notice that all the previous issues, such as generic type lists and ambiguous request names, have been resolved.

Rerunning the Application

With the fixes in place, we can now rerun our application and proceed with generating the typescript client code. Restart the application and open the Swagger endpoint. Take note of the newly generated operation IDs, which accurately represent the controller and action names. These operation IDs will be crucial when generating the typescript client code.

Using OpenAPI Typescript Generator

In addition to NSwag, there is another option available for generating typescript client code from a Swagger or OpenAPI endpoint. The OpenAPI Typescript Generator provides similar functionality and allows you to customize the output based on your requirements. Let's explore how to use this tool.

Downloading Swagger JSON

To begin, you need to download the Swagger JSON file from your Swagger or OpenAPI endpoint. Save the file locally within your project repository or a designated folder.

Running OpenAPI Command

Once you have the Swagger JSON file, you can use the OpenAPI Typescript Generator to generate the typescript client code. Make sure you have the generator tool installed globally by running the following command:

npm install -g openapi-typescript-codegen

With the OpenAPI Typescript Generator installed, run the following command:

openapi generate api -i path/to/swagger.json -o api -t axios

In this command, replace path/to/swagger.json with the path to your downloaded Swagger JSON file. Additionally, specify the output folder as api and the template as axios.

Exploring the Generated Files

After running the OpenAPI command, you will notice that the generator has created several files within the specified output folder. These files include the core components, models, services, and an index file. Each model and service will be represented as a typescript file, allowing for easy integration with your project.

The generated typescript code provides a comprehensive client SDK that allows you to interact with the API effortlessly. By exploring the different files, you can gain a better understanding of the available endpoints, request/response formats, and authentication methods supported by the generated client code.

Conclusion

In conclusion, generating a typescript client from a Swagger or OpenAPI endpoint is a powerful technique that simplifies the integration process and promotes code reusability. NSwag and the OpenAPI Typescript Generator are valuable tools that automate the generation of client code based on your API specifications. By understanding the steps involved and addressing any potential issues, you can easily generate reliable and efficient typescript client code for your applications.