Integrate OpenApi specification using openapi-generator to a ReactJs project with Typescript and Axios

24 July 2020

    #product managing
post image

As a frontend engineer, I am always looking for ways to be more effective and efficient. So the main scope is to be more productive in building the architecture of the application and get rid of the small implementations that consume time. I have spent endless hours changing the API call layer, including the DTO’s. Alongside my team, we found a way to have a common ground for frontend and backend engineers to communicate more easily and be more productive. In this article I want to make you work smarter :

- by generating functions for api calls and generating interfaces of your main objects in the application;

- by having more transparency when there is a change in the openapi specification of your project



OpenApi specification defines a programming language-agnostic interface description for REST APIs. Read more OpeApi Specification



Given an OpenApi specification (JSON or YAML file), we would like to generate the following:

- interfaces of the DTO’s;

- functions that can be used for calling APi’s;

This generated data will bring all the information you need, not just for what routes are exposed, but also which data types they use to communicate (request/response parameters).


How to accomplish these goals?

Before starting you will need a JSON or YAML file. You can read more about the format of this file on the following link OpenApi Specification Format.

This is a simple example of how a JSON file will look like: Exemple OpenApi Specification


Using this example we must take the following steps:

1. Choose a code generation tool.

For the frontend application I use OpenApi Generator.

Pros: It is straightforward and you don’t need further configuration in the application. You just need to modify the options of the command line used for generating the code (OpenApi Generator Typescript-Axios).

Cons: You need to have Java installed on your machine/docker

Also there are also other libraries that you can use:

- OpenAPi client (OpenAPi Client);

- Sw2dts (Sw2dts);

2. Define the command line that will be used to generate the code.

I use the following command line:

openapi-generator generate -i [*json file path*] -g [* client generator*] -o [*folder path where you want to generate the code*]

Now you can add this in your package.json scripts category.

I use ‘typescript-axios’ as *client generator*. I use axios because it is a popular library for http calls and I use it in most of my React projects.

I prefer to add the following option ‘ — model-name-prefix I’, because this will add to the name of Interfaces the prefix ‘I’.

Why? Maybe you need to define classes that implement these interfaces for setting some default values of the fields. This is a naming convention that will help you, especially when you will be importing both of them into other files.


How to use the generated code in your application?

One of the goals was to use generated functions for making api calls. To achieve this goal we need to import the class UserApi from the generated folder and instantiate it: const userApi = new UserApi(). The instance of the class contains all the functions that you need for making api calls to the server.

But now some questions arise:

- How do we write the config for the api call (ex: headers, timeout, baseUrl)?

- How do we add interceptors for the calls (request/response interceptors)?

Well.. the answer is quite simple. You can create an axios instance: axiosInstance: AxiosInstance = axios.create({…}). At this instance you can add interceptors and other config specifications.

After you configured your axiosInstance you can add it as a parameter when you instantiate the UserAPi:

const userApi = new UserApi(null, BASE_URL, axiosInstance);

Also if you have an api call that needs to have other configuration than the one you set up on the axiosInstance, you can override it by using the class Configuration imported from the autogenerated OpenApi folder:

const userApi = new UserApi(new Configuration({ baseOptions: {…} }), BASE_URL, axiosInstance);


Use OpenApi generated code in your sagas.

Because context in javascript is dynamic based, when you try to use a userApi instance for making an api call you will be receiving the following error: ‘this is null’.

const response = yield call(userApi.loginUser, …args); // error

To manage this error you have to provide the context in some way. The call effect supports multiple ways of providing context. You can find them in the official docs Redux Saga Call Context, here is the short version of it:

const response = yield call([userApi, userApi.loginUser], …args);


Also you need to be aware of the following:

- Never modify the generated code!

- In order to have application up to date you will need to generate the open api code at every build

- The generated code needs to be specified in the .gitignore file

- The OpenApi specification will be used by different types of applications (mobile, desktop, web, server, etc..) . So be careful when you modify them because you can impact different platforms.

- As a best practice you can keep the .json or .yaml file on a separate git repo. In this way every developer can be aware of the changes.


If you are looking for an OpenApi Specification for starting your own computer vision project, here are the standards that we are using for building our own projects:




Irimia Alexandru
Partner & Team Lead