Updated samples

modules/openapi-generator/src/main/resources/typescript/README.mustache

@@ -16,7 +16,7 @@ First build the package then run ```npm publish```
 
 ### Consuming
 
-navigate to the folder of your consuming project and run one of the following commands.
+Navigate to the folder of your consuming project and run one of the following commands.
 
 _published:_
 
@@ -28,3 +28,52 @@ _unPublished (not recommended):_
 
 ```
 npm install PATH_TO_GENERATED_PACKAGE --save
+
+### Usage
+
+Below code snippet shows exemplary usage of the configuration and the API based 
+on the typical `PetStore` example used for OpenAPI. 
+
+```
+import * as your_api from 'your_api_package'
+
+// Covers all auth methods included in your OpenAPI yaml definition
+const authConfig: your_api.AuthMethodsConfiguration = {
+    "api_key": "YOUR_API_KEY"
+}
+
+// Implements a simple middleware to modify requests before (`pre`) they are sent
+// and after (`post`) they have been received 
+class Test implements your_api.Middleware {
+    pre(context: your_api.RequestContext): Promise<your_api.RequestContext> {
+        // Modify context here and return
+        return Promise.resolve(context);
+    }
+
+    post(context: your_api.ResponseContext): Promise<your_api.ResponseContext> {
+        return Promise.resolve(context);
+    }
+
+}
+
+// Create configuration parameter object
+const configurationParameters = {
+    httpApi: new your_api.JQueryHttpLibrary(), // Can also be ignored - default is usually fine
+    baseServer: your_api.servers[0], // First server is default
+    authMethods: authConfig, // No auth is default
+    promiseMiddleware: [new Test()],
+}
+
+// Convert to actual configuration
+const config = your_api.createConfiguration(configurationParameters);
+
+// Use configuration with your_api
+const api = new your_api.PetApi(config);
+your_api.Pet p = new your_api.Pet();
+p.name = "My new pet";
+p.photoUrls = [];
+p.tags = [];
+p.status = "available";
+Promise<your_api.Pet> createdPet = api.addPet(p);
+
+```

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 
+     * OpenAPI yaml definition) 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 OpenAPI yaml definition. 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

modules/openapi-generator/src/main/resources/typescript/http/servers.mustache

@@ -14,9 +14,11 @@ export class ServerConfiguration<T extends { [key: string]: string }> 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 `{variableName}`
      *
-     * @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<T>) {
         Object.assign(this.variableConfiguration, variableConfiguration);

samples/client/others/typescript/builds/with-unique-items/README.md

@@ -16,7 +16,7 @@ First build the package then run ```npm publish```
 
 ### Consuming
 
-navigate to the folder of your consuming project and run one of the following commands.
+Navigate to the folder of your consuming project and run one of the following commands.
 
 _published:_
 
@@ -28,3 +28,52 @@ _unPublished (not recommended):_
 
 ```
 npm install PATH_TO_GENERATED_PACKAGE --save
+
+### Usage
+
+Below code snippet shows exemplary usage of the configuration and the API based 
+on the typical `PetStore` example used for OpenAPI. 
+
+```
+import * as your_api from 'your_api_package'
+
+// Covers all auth methods included in your OpenAPI yaml definition
+const authConfig: your_api.AuthMethodsConfiguration = {
+    "api_key": "YOUR_API_KEY"
+}
+
+// Implements a simple middleware to modify requests before (`pre`) they are sent
+// and after (`post`) they have been received 
+class Test implements your_api.Middleware {
+    pre(context: your_api.RequestContext): Promise<your_api.RequestContext> {
+        // Modify context here and return
+        return Promise.resolve(context);
+    }
+
+    post(context: your_api.ResponseContext): Promise<your_api.ResponseContext> {
+        return Promise.resolve(context);
+    }
+
+}
+
+// Create configuration parameter object
+const configurationParameters = {
+    httpApi: new your_api.JQueryHttpLibrary(), // Can also be ignored - default is usually fine
+    baseServer: your_api.servers[0], // First server is default
+    authMethods: authConfig, // No auth is default
+    promiseMiddleware: [new Test()],
+}
+
+// Convert to actual configuration
+const config = your_api.createConfiguration(configurationParameters);
+
+// Use configuration with your_api
+const api = new your_api.PetApi(config);
+your_api.Pet p = new your_api.Pet();
+p.name = "My new pet";
+p.photoUrls = [];
+p.tags = [];
+p.status = "available";
+Promise<your_api.Pet> createdPet = api.addPet(p);
+
+```

samples/client/others/typescript/builds/with-unique-items/configuration.ts

@@ -17,29 +17,45 @@ export interface Configuration {
  */
 export interface ConfigurationParameters {
     /**
-     * Default server to use
+     * Default server to use - a list of available servers (according to the 
+     * OpenAPI yaml definition) 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 OpenAPI yaml definition. 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

samples/client/others/typescript/builds/with-unique-items/servers.ts

@@ -14,9 +14,11 @@ export class ServerConfiguration<T extends { [key: string]: string }> 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 `{variableName}`
      *
-     * @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<T>) {
         Object.assign(this.variableConfiguration, variableConfiguration);

samples/openapi3/client/petstore/typescript/builds/browser/README.md

@@ -16,7 +16,7 @@ First build the package then run ```npm publish```
 
 ### Consuming
 
-navigate to the folder of your consuming project and run one of the following commands.
+Navigate to the folder of your consuming project and run one of the following commands.
 
 _published:_
 
@@ -28,3 +28,52 @@ _unPublished (not recommended):_
 
 ```
 npm install PATH_TO_GENERATED_PACKAGE --save
+
+### Usage
+
+Below code snippet shows exemplary usage of the configuration and the API based 
+on the typical `PetStore` example used for OpenAPI. 
+
+```
+import * as your_api from 'your_api_package'
+
+// Covers all auth methods included in your OpenAPI yaml definition
+const authConfig: your_api.AuthMethodsConfiguration = {
+    "api_key": "YOUR_API_KEY"
+}
+
+// Implements a simple middleware to modify requests before (`pre`) they are sent
+// and after (`post`) they have been received 
+class Test implements your_api.Middleware {
+    pre(context: your_api.RequestContext): Promise<your_api.RequestContext> {
+        // Modify context here and return
+        return Promise.resolve(context);
+    }
+
+    post(context: your_api.ResponseContext): Promise<your_api.ResponseContext> {
+        return Promise.resolve(context);
+    }
+
+}
+
+// Create configuration parameter object
+const configurationParameters = {
+    httpApi: new your_api.JQueryHttpLibrary(), // Can also be ignored - default is usually fine
+    baseServer: your_api.servers[0], // First server is default
+    authMethods: authConfig, // No auth is default
+    promiseMiddleware: [new Test()],
+}
+
+// Convert to actual configuration
+const config = your_api.createConfiguration(configurationParameters);
+
+// Use configuration with your_api
+const api = new your_api.PetApi(config);
+your_api.Pet p = new your_api.Pet();
+p.name = "My new pet";
+p.photoUrls = [];
+p.tags = [];
+p.status = "available";
+Promise<your_api.Pet> createdPet = api.addPet(p);
+
+```

samples/openapi3/client/petstore/typescript/builds/browser/configuration.ts

@@ -17,29 +17,45 @@ export interface Configuration {
  */
 export interface ConfigurationParameters {
     /**
-     * Default server to use
+     * Default server to use - a list of available servers (according to the 
+     * OpenAPI yaml definition) 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 OpenAPI yaml definition. 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

samples/openapi3/client/petstore/typescript/builds/browser/servers.ts

@@ -14,9 +14,11 @@ export class ServerConfiguration<T extends { [key: string]: string }> 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 `{variableName}`
      *
-     * @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<T>) {
         Object.assign(this.variableConfiguration, variableConfiguration);

samples/openapi3/client/petstore/typescript/builds/composed-schemas/README.md

@@ -16,7 +16,7 @@ First build the package then run ```npm publish```
 
 ### Consuming
 
-navigate to the folder of your consuming project and run one of the following commands.
+Navigate to the folder of your consuming project and run one of the following commands.
 
 _published:_
 
@@ -28,3 +28,52 @@ _unPublished (not recommended):_
 
 ```
 npm install PATH_TO_GENERATED_PACKAGE --save
+
+### Usage
+
+Below code snippet shows exemplary usage of the configuration and the API based 
+on the typical `PetStore` example used for OpenAPI. 
+
+```
+import * as your_api from 'your_api_package'
+
+// Covers all auth methods included in your OpenAPI yaml definition
+const authConfig: your_api.AuthMethodsConfiguration = {
+    "api_key": "YOUR_API_KEY"
+}
+
+// Implements a simple middleware to modify requests before (`pre`) they are sent
+// and after (`post`) they have been received 
+class Test implements your_api.Middleware {
+    pre(context: your_api.RequestContext): Promise<your_api.RequestContext> {
+        // Modify context here and return
+        return Promise.resolve(context);
+    }
+
+    post(context: your_api.ResponseContext): Promise<your_api.ResponseContext> {
+        return Promise.resolve(context);
+    }
+
+}
+
+// Create configuration parameter object
+const configurationParameters = {
+    httpApi: new your_api.JQueryHttpLibrary(), // Can also be ignored - default is usually fine
+    baseServer: your_api.servers[0], // First server is default
+    authMethods: authConfig, // No auth is default
+    promiseMiddleware: [new Test()],
+}
+
+// Convert to actual configuration
+const config = your_api.createConfiguration(configurationParameters);
+
+// Use configuration with your_api
+const api = new your_api.PetApi(config);
+your_api.Pet p = new your_api.Pet();
+p.name = "My new pet";
+p.photoUrls = [];
+p.tags = [];
+p.status = "available";
+Promise<your_api.Pet> createdPet = api.addPet(p);
+
+```

samples/openapi3/client/petstore/typescript/builds/composed-schemas/configuration.ts

@@ -17,29 +17,45 @@ export interface Configuration {
  */
 export interface ConfigurationParameters {
     /**
-     * Default server to use
+     * Default server to use - a list of available servers (according to the 
+     * OpenAPI yaml definition) 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 OpenAPI yaml definition. 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

samples/openapi3/client/petstore/typescript/builds/composed-schemas/servers.ts

@@ -14,9 +14,11 @@ export class ServerConfiguration<T extends { [key: string]: string }> 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 `{variableName}`
      *
-     * @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<T>) {
         Object.assign(this.variableConfiguration, variableConfiguration);

samples/openapi3/client/petstore/typescript/builds/default/README.md

@@ -16,7 +16,7 @@ First build the package then run ```npm publish```
 
 ### Consuming
 
-navigate to the folder of your consuming project and run one of the following commands.
+Navigate to the folder of your consuming project and run one of the following commands.
 
 _published:_
 
@@ -28,3 +28,52 @@ _unPublished (not recommended):_
 
 ```
 npm install PATH_TO_GENERATED_PACKAGE --save
+
+### Usage
+
+Below code snippet shows exemplary usage of the configuration and the API based 
+on the typical `PetStore` example used for OpenAPI. 
+
+```
+import * as your_api from 'your_api_package'
+
+// Covers all auth methods included in your OpenAPI yaml definition
+const authConfig: your_api.AuthMethodsConfiguration = {
+    "api_key": "YOUR_API_KEY"
+}
+
+// Implements a simple middleware to modify requests before (`pre`) they are sent
+// and after (`post`) they have been received 
+class Test implements your_api.Middleware {
+    pre(context: your_api.RequestContext): Promise<your_api.RequestContext> {
+        // Modify context here and return
+        return Promise.resolve(context);
+    }
+
+    post(context: your_api.ResponseContext): Promise<your_api.ResponseContext> {
+        return Promise.resolve(context);
+    }
+
+}
+
+// Create configuration parameter object
+const configurationParameters = {
+    httpApi: new your_api.JQueryHttpLibrary(), // Can also be ignored - default is usually fine
+    baseServer: your_api.servers[0], // First server is default
+    authMethods: authConfig, // No auth is default
+    promiseMiddleware: [new Test()],
+}
+
+// Convert to actual configuration
+const config = your_api.createConfiguration(configurationParameters);
+
+// Use configuration with your_api
+const api = new your_api.PetApi(config);
+your_api.Pet p = new your_api.Pet();
+p.name = "My new pet";
+p.photoUrls = [];
+p.tags = [];
+p.status = "available";
+Promise<your_api.Pet> createdPet = api.addPet(p);
+
+```

samples/openapi3/client/petstore/typescript/builds/default/configuration.ts

@@ -17,29 +17,45 @@ export interface Configuration {
  */
 export interface ConfigurationParameters {
     /**
-     * Default server to use
+     * Default server to use - a list of available servers (according to the 
+     * OpenAPI yaml definition) 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 OpenAPI yaml definition. 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

samples/openapi3/client/petstore/typescript/builds/default/servers.ts

@@ -14,9 +14,11 @@ export class ServerConfiguration<T extends { [key: string]: string }> 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 `{variableName}`
      *
-     * @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<T>) {
         Object.assign(this.variableConfiguration, variableConfiguration);

samples/openapi3/client/petstore/typescript/builds/deno/configuration.ts

@@ -17,29 +17,45 @@ export interface Configuration {
  */
 export interface ConfigurationParameters {
     /**
-     * Default server to use
+     * Default server to use - a list of available servers (according to the 
+     * OpenAPI yaml definition) 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 OpenAPI yaml definition. 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

samples/openapi3/client/petstore/typescript/builds/deno/servers.ts

@@ -14,9 +14,11 @@ export class ServerConfiguration<T extends { [key: string]: string }> 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 `{variableName}`
      *
-     * @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<T>) {
         Object.assign(this.variableConfiguration, variableConfiguration);

samples/openapi3/client/petstore/typescript/builds/inversify/README.md

@@ -16,7 +16,7 @@ First build the package then run ```npm publish```
 
 ### Consuming
 
-navigate to the folder of your consuming project and run one of the following commands.
+Navigate to the folder of your consuming project and run one of the following commands.
 
 _published:_
 
@@ -28,3 +28,52 @@ _unPublished (not recommended):_
 
 ```
 npm install PATH_TO_GENERATED_PACKAGE --save
+
+### Usage
+
+Below code snippet shows exemplary usage of the configuration and the API based 
+on the typical `PetStore` example used for OpenAPI. 
+
+```
+import * as your_api from 'your_api_package'
+
+// Covers all auth methods included in your OpenAPI yaml definition
+const authConfig: your_api.AuthMethodsConfiguration = {
+    "api_key": "YOUR_API_KEY"
+}
+
+// Implements a simple middleware to modify requests before (`pre`) they are sent
+// and after (`post`) they have been received 
+class Test implements your_api.Middleware {
+    pre(context: your_api.RequestContext): Promise<your_api.RequestContext> {
+        // Modify context here and return
+        return Promise.resolve(context);
+    }
+
+    post(context: your_api.ResponseContext): Promise<your_api.ResponseContext> {
+        return Promise.resolve(context);
+    }
+
+}
+
+// Create configuration parameter object
+const configurationParameters = {
+    httpApi: new your_api.JQueryHttpLibrary(), // Can also be ignored - default is usually fine
+    baseServer: your_api.servers[0], // First server is default
+    authMethods: authConfig, // No auth is default
+    promiseMiddleware: [new Test()],
+}
+
+// Convert to actual configuration
+const config = your_api.createConfiguration(configurationParameters);
+
+// Use configuration with your_api
+const api = new your_api.PetApi(config);
+your_api.Pet p = new your_api.Pet();
+p.name = "My new pet";
+p.photoUrls = [];
+p.tags = [];
+p.status = "available";
+Promise<your_api.Pet> createdPet = api.addPet(p);
+
+```

samples/openapi3/client/petstore/typescript/builds/inversify/configuration.ts

@@ -17,29 +17,45 @@ export interface Configuration {
  */
 export interface ConfigurationParameters {
     /**
-     * Default server to use
+     * Default server to use - a list of available servers (according to the 
+     * OpenAPI yaml definition) 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 OpenAPI yaml definition. 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

samples/openapi3/client/petstore/typescript/builds/inversify/servers.ts

@@ -14,9 +14,11 @@ export class ServerConfiguration<T extends { [key: string]: string }> 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 `{variableName}`
      *
-     * @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<T>) {
         Object.assign(this.variableConfiguration, variableConfiguration);

samples/openapi3/client/petstore/typescript/builds/jquery/README.md

@@ -16,7 +16,7 @@ First build the package then run ```npm publish```
 
 ### Consuming
 
-navigate to the folder of your consuming project and run one of the following commands.
+Navigate to the folder of your consuming project and run one of the following commands.
 
 _published:_
 
@@ -28,3 +28,52 @@ _unPublished (not recommended):_
 
 ```
 npm install PATH_TO_GENERATED_PACKAGE --save
+
+### Usage
+
+Below code snippet shows exemplary usage of the configuration and the API based 
+on the typical `PetStore` example used for OpenAPI. 
+
+```
+import * as your_api from 'your_api_package'
+
+// Covers all auth methods included in your OpenAPI yaml definition
+const authConfig: your_api.AuthMethodsConfiguration = {
+    "api_key": "YOUR_API_KEY"
+}
+
+// Implements a simple middleware to modify requests before (`pre`) they are sent
+// and after (`post`) they have been received 
+class Test implements your_api.Middleware {
+    pre(context: your_api.RequestContext): Promise<your_api.RequestContext> {
+        // Modify context here and return
+        return Promise.resolve(context);
+    }
+
+    post(context: your_api.ResponseContext): Promise<your_api.ResponseContext> {
+        return Promise.resolve(context);
+    }
+
+}
+
+// Create configuration parameter object
+const configurationParameters = {
+    httpApi: new your_api.JQueryHttpLibrary(), // Can also be ignored - default is usually fine
+    baseServer: your_api.servers[0], // First server is default
+    authMethods: authConfig, // No auth is default
+    promiseMiddleware: [new Test()],
+}
+
+// Convert to actual configuration
+const config = your_api.createConfiguration(configurationParameters);
+
+// Use configuration with your_api
+const api = new your_api.PetApi(config);
+your_api.Pet p = new your_api.Pet();
+p.name = "My new pet";
+p.photoUrls = [];
+p.tags = [];
+p.status = "available";
+Promise<your_api.Pet> createdPet = api.addPet(p);
+
+```

samples/openapi3/client/petstore/typescript/builds/jquery/configuration.ts

@@ -17,29 +17,45 @@ export interface Configuration {
  */
 export interface ConfigurationParameters {
     /**
-     * Default server to use
+     * Default server to use - a list of available servers (according to the 
+     * OpenAPI yaml definition) 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 OpenAPI yaml definition. 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

samples/openapi3/client/petstore/typescript/builds/jquery/servers.ts

@@ -14,9 +14,11 @@ export class ServerConfiguration<T extends { [key: string]: string }> 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 `{variableName}`
      *
-     * @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<T>) {
         Object.assign(this.variableConfiguration, variableConfiguration);

samples/openapi3/client/petstore/typescript/builds/object_params/README.md

@@ -16,7 +16,7 @@ First build the package then run ```npm publish```
 
 ### Consuming
 
-navigate to the folder of your consuming project and run one of the following commands.
+Navigate to the folder of your consuming project and run one of the following commands.
 
 _published:_
 
@@ -28,3 +28,52 @@ _unPublished (not recommended):_
 
 ```
 npm install PATH_TO_GENERATED_PACKAGE --save
+
+### Usage
+
+Below code snippet shows exemplary usage of the configuration and the API based 
+on the typical `PetStore` example used for OpenAPI. 
+
+```
+import * as your_api from 'your_api_package'
+
+// Covers all auth methods included in your OpenAPI yaml definition
+const authConfig: your_api.AuthMethodsConfiguration = {
+    "api_key": "YOUR_API_KEY"
+}
+
+// Implements a simple middleware to modify requests before (`pre`) they are sent
+// and after (`post`) they have been received 
+class Test implements your_api.Middleware {
+    pre(context: your_api.RequestContext): Promise<your_api.RequestContext> {
+        // Modify context here and return
+        return Promise.resolve(context);
+    }
+
+    post(context: your_api.ResponseContext): Promise<your_api.ResponseContext> {
+        return Promise.resolve(context);
+    }
+
+}
+
+// Create configuration parameter object
+const configurationParameters = {
+    httpApi: new your_api.JQueryHttpLibrary(), // Can also be ignored - default is usually fine
+    baseServer: your_api.servers[0], // First server is default
+    authMethods: authConfig, // No auth is default
+    promiseMiddleware: [new Test()],
+}
+
+// Convert to actual configuration
+const config = your_api.createConfiguration(configurationParameters);
+
+// Use configuration with your_api
+const api = new your_api.PetApi(config);
+your_api.Pet p = new your_api.Pet();
+p.name = "My new pet";
+p.photoUrls = [];
+p.tags = [];
+p.status = "available";
+Promise<your_api.Pet> createdPet = api.addPet(p);
+
+```

samples/openapi3/client/petstore/typescript/builds/object_params/configuration.ts

@@ -17,29 +17,45 @@ export interface Configuration {
  */
 export interface ConfigurationParameters {
     /**
-     * Default server to use
+     * Default server to use - a list of available servers (according to the 
+     * OpenAPI yaml definition) 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 OpenAPI yaml definition. 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

samples/openapi3/client/petstore/typescript/builds/object_params/servers.ts

@@ -14,9 +14,11 @@ export class ServerConfiguration<T extends { [key: string]: string }> 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 `{variableName}`
      *
-     * @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<T>) {
         Object.assign(this.variableConfiguration, variableConfiguration);