OpenAPITools / OpenAPITools/openapi-generator

[REQ][Typescript] Add an option to generate an API Facade

Open
#11,269 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Rationale

It's useful to have a single place to manage all logic relating to generated client stubs.
As it currently stands, the generated API stubs have to be manually imported and directly used.

Description

Sometimes, Configurations have to be computed during runtime, APIs may need proxying or rate limiting and so forth.
This also improves ease of maintenance- adding a new required configuration header, for example, could quickly become messy for larger projects. The same change would be made trivial with a facade.

Related issues/PRs

None found. Apologies if I've missed any.

Suggest a fix/enhancement

A very basic template could be used to generate a simple facade for all generated client API stubs.
Said template can then be left as is for a plug-and-play experience or tailored to the user's specific needs.

The generated facade could looks something like the below snippet.

If anyone else feels this may be useful, I can probably create a P.R for this.
      Cheers



Example facade.
Users can pass a static configuration object or a function to dynamically get the current configuration.
May be useful for some cases, mostly in stateful projects.



import { Configuration, AuthenticationApi, NotesApi, UsersApi } from '../api';

export type ConfigurationGetter = () => Configuration | undefined;

export class ApiFacade {

	private _config?: Configuration | ConfigurationGetter;

	/**
	 * API Docs go here
	 *
	 * @readonly
	 * @type {AuthenticationApi}
	 * @memberof ApiFacade
	 */
	public get authenticationApi(): AuthenticationApi {
		return new AuthenticationApi(this.getConfig())
	}

	/**
	 * API Docs go here
	 *
	 * @readonly
	 * @type {NotesApi}
	 * @memberof ApiFacade
	 */
	public get notesApi(): NotesApi {
		return new NotesApi(this.getConfig())
	}

	/**
	 * API Docs go here
	 *
	 * @readonly
	 * @type {UsersApi}
	 * @memberof ApiFacade
	 */
	public get usersApi(): UsersApi {
		return new UsersApi(this.getConfig())
	}

	public constructor(config?: Configuration | ConfigurationGetter) {
		this._config = typeof config === 'function' ? config() : config;
	}

	private getConfig(): Configuration | undefined {
		return typeof this._config === 'function' ? this._config() : this._config;
	}
}

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the TypeScript generator's templates and entry point for generated client API stubs. Compare the existing Configuration and API stub generation with the proposed ApiFacade example, then define how the option and generated output should behave. Done means the generator can optionally produce a facade that supports static or dynamic configuration without changing the default output.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.