Rewrite of TypeScript Generators

Motivation

We currently have 7 (!) different generators for TypeScript, which do not share common code. This makes introducing bug fixes to the TypeScript generator family very hard.

Goal

Create a general framework which can be used in any OOP language - unifying the generator structure and making the project easier to work with. At the beginning, I would like to look into merging the TypeScript generators into one and improve the architecture during the implementation.

Feedback

Tear the architecture apart! Focus on the bigger picture first (e.g. missing some important feature? something which is hard to implement with this architecture?) and then go into details (e.g. missing variables). The TODOs in the text below mark parts which I did not think (enough) about yet. Feel free to fill in what’s missing.

Architecture

Architecture (looks weird if I include it as an image. sorry!)

The key idea is to extract everything into its own component and hide it behind an interface. The key advantage of this architecture is

• extendability e.g. new http libraries or more modifiers for requests e.g. a request is fed through multiple components which modify it according to their rules e.g. server sets the correct request url
• testability - the components can be tested in isolation and can be mocked
• less duplication of code for different frameworks in the same language

I’ll go through the different components one by one and try to explain the idea.

HTTP Library

This part should be clear - hide the details of making a HTTP request behind an interface so that we can use different libraries without changing the API Client. To achieve this we create our own data structures for requests and responses.

TODO: Use promises/futures?

Authentication

Same idea as HTTP library. I want to highlight one part: the authentication interface has a method apply(Request r). This method applies the authentication scheme to the given request e.g. in the case of an API Key it would append the api key.

TODO: OAuth work flow with this implementation?

Response Models & Param Models

TODO: Should this be separated or can response & param models be used interchangeably? i.e. param Pet can also be a response model? If yes these two components should be merged.

This component contains model classes for each parameter & response as well as a (object) serializer and deserializer for these models (e.g. Array<JsonObject> in the API response is transformed to Array<Pet> by the ObjectDeserializer).

Server

This component contains the different servers as defined in OAS.

TODO: handling of variables. I would propose to offer setters for each variable. Variables are not yet supported in OpenAPITools. See #793

Config

See current implementation.

API Client

The API client coordinates all other components.

1. Serializes the input parameters
2. creates a new request r
3. calls Server#apply(r)
4. calls `Authentication#apply®
5. deserializes the response
6. returns a promise with the deserialized response

Callbacks in OAS 3

TODO: create server, hide it behind an interface to make the library exchangeable and create one method for each callback endpoint.

Framework Specific Code

Anything framework specific goes here and acts as a proxy to APIClient.

Technical Committee

@TiFu (2017/07) @taxpon (2017/07) @sebastianhaas (2017/07) @kenisteward (2017/07) @Vrolijkx (2017/09) @macjohnny (2018/01)

Project

William created a project for this issue: https://github.com/OpenAPITools/openapi-generator/projects/4

[forresthopkinsa]

IMO it’s critical that the generalized Typescript generator has a lot more explanation in its readme pertaining to what it is and whether or not people should use it.

It’s pretty confusing seeing “Typescript” and “Typescript-Fetch” right next to each other, with only this to distinguish them:

	typescript	typescript-fetch
stability	experimental	stable
type	client	client
language	typescript	typescript
templating	mustache	mustache
helpTxt	Generates a TypeScript client library using Fetch API (beta).	Generates a TypeScript client library using Fetch API (beta).

[acornett]

Not sure if this has been brought up elsewhere, but one issue I’m having adopting the generated typescript client is the use of namespaces for enums. If the typescript generator is being overhauled could alternate code styles be considered? Babel 7 doesn’t support namespaces in typescript (https://babeljs.io/docs/en/babel-plugin-transform-typescript) and advises the use of ES2015 modules instead. Some parts of the code are already using string unions as instead of a defined enum, or the enum could be declared without the namespace and use a prefix of the enclosing type for uniqueness.