Setup Swagger CodeGen for automatic generation of an JS api client

[antonplagemann]

As a developer
I want to have my frontend api client to be generated automatically from the api documentation
so that a correct api documentation is enforced and I do not have to manually change/update/create the api client manually.

Description:

Setup automatic api client generation from swagger docs using inline JSDoc/TSDoc comments.

🟢 In scope:

• Setup Swagger CodeGen for automatic generation of an JS api client

🔴 Not in scope:

• Create a new repository jimmi-api-client
• Add the new repo as submodule in the main monorepo frontend section.
• Setup pipelines to automate the above process (maybe with this module)
• Write features or api specs (except some testing specs maybe)
• Begin api documentation

What should be the result?

tbd

[p-fruck]

Design change

After trying to create a generater for swagger-codegen, I did a little bit (rather quite a lot) of research and discovered, that there are actually two similar projects, namely swagger-codegen, the use of which I suggested until today, and the openapi-generator, which I will suggest from now on. The openapi generator is actually a fork of swagger-codegen, see here for more details.

I've analyzed the codebases of multiple typescript related code generators of both projects and here are my findings:

How swagger codegen works

Swagger codegen has an abstract class, from which each language is derived. What might sound logical at a first glance becomes a huge limitation later on. Since there are multiple kinds of clients one might generate (node, deno, fetch, jquery, angular, you name it), it is very limiting to implement the common typescript logic (generating classes and interfaces from the api spec) in each generator individually, without sharing anything of the common codebase. Typescript is a mess at swagger-codegen, every generator has a different implementation of typings (e.g. the fetch-client does not have any typings, which makes it pretty much useless).

How openapi codegen works

This project has IMHO a much better approach. The abstract generator class is derived into a generic typescript class. This generic typescript class is then derived into more specialized generators, e.g. typescript-angular. Therefore, openapi codegen should have much more reliable types, since all typescript related generators can collectively improve typings and do have to maintain their own implementation. This project also has a more widespread adoption in the typescript community, as it supports more frameworks and later versions of them compared to swagger codegen.

Also, openapi has the ability to distinguish platforms (currently browser, node and deno) in addition to further customization options like RxJS

Decision

For me, the logical consequence is to use the openapi generator over swagger codegen, as (in regards to typescript) it is not only more capable, but also better extensible and therefore future proof.

Generating an API client

The generation of the API client is straight forward. I've created the following config.yml file:

---
platform: deno
supportsES6: true

Afterwards I launched the container using the following command:

podman run --rm \
    -v .:/local:Z \
    openapitools/openapi-generator-cli generate \
    -i https://petstore.swagger.io/v2/swagger.json \
    -c /local/config.yml \
    -g typescript \
    -o /local/out/

This will create a deno compatible api client in ./out/. The only thing left is to rename the generated index.ts to mod.ts.