Generating typescript API client from Swagger

When it comes to API Test Frameworks, I prefer to generate code and not to write everything manually. In my current company, we managed to build a Test Framework using swagger-codegen and Java bindings. It was relatively simple to set up a process where we would generate API clients using swagger-codegen, push them to our Nexus repository and use this library as a dependency in our Test Framework. It works well for us, but recently we concluded that we need to build something similar in Typescript. So, based on our previous experience we managed to define the set of requirements for the generated client:

• We should be able to have multiple instances of the same API Client
• We should be able to set custom headers (request-trace-id, Authorization, etc) for every API Client
• We should be able to set request/response interceptors to:
  • properly log request/response details (we were using plinter library for that)
  • attach request/response details into Allure report
• And of course we would like to generate Api client in typescript

At first, I thought that I will use swagger-codegen just like I used it for generating our Java API clients. But it was unpleasantly surprising to see that the swagger-codegen has next typescript options:

• Typescript (Node) - it's using request under the hood which is deprecated
• Typescript (Angular) - which is handy to be used in Angular projects, which was not my case
• Typescript (Fetch) - the problem here is that you can't get multiple instances of the same API Client. fetch is global and therefore it's impossible to set different Authorization headers for the same API Client
• Typescript (jQuery) - obviously also is not an option for our case :)

So I started looking into other options and I discovered that it's not that easy to find a library, that would match all my requirements.

Eventually, I found a solution, but I would like to tell more about my journey and give a short review of every library I could find on the web.

Swagger-typescript-codegen

The first library I found was this one. It looked promising at first, but then I discovered that it's using superagent under the hood and that and this library is not using classes for API clients generation. For my purpose, I would prefer Axios, so I decided not to go with this library

Swagger-js-codegen

This library is looking for a new maintainer and is not under active development, so not an option for me either.

Swagger-axios-codegen

At first, I was excited to see this library, since it was using Axios and I was able to pass custom Axios instance. The problem was that it was impossible to create multiple instances of the same API Client, but I've spent more than a week trying to make local version to work for me:( .
After finally resolving the issue, I have discovered another issue - the library doesn't support generating parameters by reference, which is quite serious. Even with these issues, I decided to give it a try and generate a client for me - unfortunately, the generated code was not even close to what I was expecting and I decided not to proceed with it.

Swagger-to-ts

From what I understood this library only generates models of requests/responses and not the actual client.

Openapi-generator 🏆

And this is the winner! Here's why:

• It supports Swagger V2 and V3
• It has typescript-Axios client generation
• You can create multiple instances of the same API Client
• You can pass custom Axios instance to the client
• Axios allows you to set custom headers and interceptors.

In case you want to quickly try it for yourself, you can do the following:

wget https://petstore.swagger.io/v2/swagger.json

wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/5.0.0-beta/openapi-generator-cli-5.0.0-beta.jar -O openapi-generator-cli.jar

openapi-generator generate \
    -i swagger.json \
    -o api-client \
    -g typescript-axios
    --artifact-version 1.0.0-SNAPSHOT

This should be enough to see what is the result and whether it fit your needs.

There was a moment when I thought that we would use swagger-codegen for generating only models for request/response and write API client methods manually, but I'm glad that I tried openapi-generator at the end.

I hope my findings will be helpful for other people as well.

Happy coding :)