OpenAPI 👉 Typescript / Runtypes / Rest Client

Status: proposed (not all options are fully evaluated)
Date: 2021-03-29

OpenAPI (formerly Swagger) is a way to describe a REST API. It has slowly become a business standard, used by large tech companies as well as small. The Open Source community has built the OpenAPI specification to improve the reliability of REST APIs, with it you can define types and methods of an API. The community has also built tools to generate server and client code for these APIs.

The benefits of code generators are obviously having to write less code. There are many alternatives to generate clients, based on OpenAPI – most of them have issues. The issues are typically unorganized source code, being unmaintaned, outdated targets (the generated Typescript code is outdated) or being unfinished. These issues are the fundation of this proposal, which is essentially rewriting/building a OpenAPI to Typescript client generator.

Context and Problem Statement

We cannot find a OpenAPI Generator that is maintained, has updated targes and is well-organized. Typescript clients generated by the available OpenAPI Generators are consequently outdated and less desirable to use. Users end up writing clients manually 👀

Decision Drivers

Utilize modern Typescript (e.g. we don't want request as a dependency)
Runtype validation for static types (runtypes, iots etc.)
We don't want to maintain a bunch of code, we want to reuse what is already there.
Support all OpenAPI versions (at least the latest)
Use some form of CodeWriter which can be updated instead of a template (?)
Add features to create specific input/output types (for OpenAPI specs that are weird)

Considered Options

Either contribute or fork one of these:

Raw

1-technocreatives--openapi-eller.md

technocreatives/openapi-eller

Pro

Well-structured.
Design of code (separation of concerns)

Contra

No release above v1.0.0 after 2 years.
Nearly a year since last release

Raw

2-drwpow--openapi-typescript.md

drwpow/openapi-typescript

Pro

Someone already wants to use runtype validation! (But for server side) drwpow/openapi-typescript#531
Vivid community (+700 stars, 30+ contributors, 10k+ weekly downloads)

Contra

Uses templates.
Only builds typescript types

Raw

3-OpenAPITools--openapi-generator.md

OpenAPITools/openapi-generator

There are few things that is good with OpenAPITools/openapi-generator. It has a huge user-base, but has more than 2000+ open issues, many of which are really old and still without any reply. The least updated one are from 2018, still waiting for a reply.

A few examples from my personal experience;

OpenAPITools/openapi-generator#6597 (Issue was posted in june 2020, bumped in august, september and october of 2020. In november 2020, I closed the issue because of no answer and had to move away from the library – reopened due to a community member still wanted it fixed. Still isn't fixed, just had a workaround.