API Generator
Date: 2023-09-14
Status: accepted
Context
Statista uses a lot of APIs between the frontend and the backend for communication. These APIs are usually based on an OpenAPI contract.
To leverage these specifications and help development, we would like to generate TypeScript typings from it. This will help to ensure that (during development) we adhere to the specification. It also allows us to identify issues and false assumptions about availability of data fields. Nonetheless we gain code completion and improved developer experience with this created type information.
There are a lot of ways to generate typescript types from these specifications. Many of them include to install tools from the 'backend world' like Java or Docker. There are a few options to generate types with just node.js.
Decision
After trying multiple tools we decided to lean on openapi-typescript and the
accompanied helpers openapi-typescript-helpers and openapi-fetch.
These do not required any additional tooling and are based on node.js/TypeScript.
Consequences
The generated types are free of external dependencies and do not require runtime
code. The openapi-fetch library leans on the standard fetch api and provides
a thin wrapper to bind url, parameters and responses together.
The assumption here is, that only one OpenAPI specification per application is required. But the tool will allow for generating types from multiple specification.