Skip to content
GitLab
Closed
Issue created by Administrator@rootContributor

Rewrite of TypeScript Generators

Created by: TiFu

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 (closed)

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(r)
  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