From 358baae19c5bd313f15a43a093f2f6f54ec8e110 Mon Sep 17 00:00:00 2001 From: Tino Fuhrmann Date: Sun, 29 Aug 2021 21:52:57 +0200 Subject: [PATCH] Added additional documentation for configuration object --- .../typescript/configuration.mustache | 28 +++++++++++++++---- .../typescript/http/servers.mustache | 6 ++-- 2 files changed, 26 insertions(+), 8 deletions(-) diff --git a/modules/openapi-generator/src/main/resources/typescript/configuration.mustache b/modules/openapi-generator/src/main/resources/typescript/configuration.mustache index a281b22db0a..330273a7e1c 100644 --- a/modules/openapi-generator/src/main/resources/typescript/configuration.mustache +++ b/modules/openapi-generator/src/main/resources/typescript/configuration.mustache @@ -24,29 +24,45 @@ export interface Configuration { */ export interface ConfigurationParameters { /** - * Default server to use + * Default server to use - a list of available servers (according to the + * spec) is included in the `servers` const in `./servers`. You can also + * create your own server with the `ServerConfiguration` class from the same + * file. */ baseServer?: BaseServerConfiguration; /** - * HTTP library to use e.g. IsomorphicFetch + * HTTP library to use e.g. IsomorphicFetch. This can usually be skipped as + * all generators come with a default library. + * If available, additional libraries can be imported from `./http/*` */ httpApi?: HttpLibrary; + /** - * The middlewares which will be applied to requests and responses + * The middlewares which will be applied to requests and responses. You can + * add any number of middleware components to modify requests before they + * are sent or before they are deserialized by implementing the `Middleware` + * interface defined in `./middleware` */ middleware?: Middleware[]; /** - * Configures all middlewares using the promise api instead of observables (which Middleware uses) + * Configures middleware functions that return promises instead of + * Observables (which are used by `middleware`). Otherwise allows for the + * same functionality as `middleware`, i.e., modifying requests before they + * are sent and before they are deserialized. */ promiseMiddleware?: PromiseMiddleware[]; /** - * Configuration for the available authentication methods + * Configuration for the available authentication methods (e.g., api keys) + * according to the spec. For the definition, please refer to + * `./auth/auth` */ authMethods?: AuthMethodsConfiguration } /** - * Configuration factory function + * Provide your `ConfigurationParameters` to this function to get a `Configuration` + * object that can be used to configure your APIs (in the constructor or + * for each request individually). * * If a property is not included in conf, a default is used: * - baseServer: server1 diff --git a/modules/openapi-generator/src/main/resources/typescript/http/servers.mustache b/modules/openapi-generator/src/main/resources/typescript/http/servers.mustache index 7e204c3e027..eb94d2a4eec 100644 --- a/modules/openapi-generator/src/main/resources/typescript/http/servers.mustache +++ b/modules/openapi-generator/src/main/resources/typescript/http/servers.mustache @@ -14,9 +14,11 @@ export class ServerConfiguration implements public constructor(private url: string, private variableConfiguration: T) {} /** - * Sets the value of the variables of this server. + * Sets the value of the variables of this server. Variables are included in + * the `url` of this ServerConfiguration in the form `{key}` * - * @param variableConfiguration a partial variable configuration for the variables contained in the url + * @param variableConfiguration a partial variable configuration for the + * variables contained in the url */ public setVariables(variableConfiguration: Partial) { Object.assign(this.variableConfiguration, variableConfiguration);