Skip to content

Instantly share code, notes, and snippets.

@simenandre

simenandre/0-runtypes-openapi-clients.md

Last active September 22, 2022 02:49
Show Gist options
  • Save simenandre/a0031905833bc58d233451fe537f3019 to your computer and use it in GitHub Desktop.
Save simenandre/a0031905833bc58d233451fe537f3019 to your computer and use it in GitHub Desktop.
Download ZIP
Generate clients based on Runtypes (and other awesome tech) from OpenAPI
Raw
0-runtypes-openapi-clients.md

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
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.

Pro

  • Large community.

Contra

  • Based on Java.
  • Has a lot of issues.
Raw
4-mermade--openapi-codegen.md
Raw
5-PaulDLW--typescript-openapi-generator.md
Raw
8-ferdikoomen--openapi-typescript-codegen.md

ferdikoomen/openapi-typescript-codegen

Pro

  • Maintained (just 17 days since last release)
  • Good Community

Contra

  • Large user base, but only one maintainer
  • Technical debt.
  • Global variable.
  • Uses templates.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment