Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation of Configuration/ConfigurationParameter for consolidated TypeScript generator #10283

Merged
merged 7 commits into from
Jan 11, 2023
Merged

Documentation of Configuration/ConfigurationParameter for consolidated TypeScript generator #10283

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
358baae
Added additional documentation for configuration object
TiFu Aug 29, 2021
cd5da90
Regenerate samples
TiFu Aug 29, 2021
81ede19
Added exemplary usage of API to README.md
TiFu Oct 22, 2021
a5774db
Updated README, refined wording
TiFu Oct 22, 2021
be67222
Added example for calling the API
TiFu Jan 10, 2023
0263114
Regenerated samples
TiFu Jan 10, 2023
a0225de
Updated samples
TiFu Jan 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 50 additions & 1 deletion modules/openapi-generator/src/main/resources/typescript/README.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:_

Expand All @@ -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);
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be great to also see how you would make a call off of this api instance.
It seems like we'd do something like api.getUsers(), but I'm getting tripped up by POST requests.

It seems like you'd do something like:

// Seems like object arguments need to be namespaced, and that's based on the model name?
// If there's an option to not-namespace params I'd love to know it
api.createUser({createUserRequest: { email: 'email', password: 'password'}})

This seems to work for me if the SDK is making a call from one localhost port to another, but in my prod env it strips out the request payload. I imagine that's because I'm missing some kind of config option, and seeing how you do this would be super helpful information.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have added another couple lines with an example in the latest commit. Hope that explains it a bit more. There's also some examples in the tests folder under samples/openapi3/client/petstore/typescript/ - hope this helps with debugging your problem.

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);

```
28 changes: 22 additions & 6 deletions modules/openapi-generator/src/main/resources/typescript/configuration.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 4 additions & 2 deletions modules/openapi-generator/src/main/resources/typescript/http/servers.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
51 changes: 50 additions & 1 deletion samples/client/others/typescript/builds/with-unique-items/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:_

Expand All @@ -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);

```
28 changes: 22 additions & 6 deletions samples/client/others/typescript/builds/with-unique-items/configuration.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 4 additions & 2 deletions samples/client/others/typescript/builds/with-unique-items/servers.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
51 changes: 50 additions & 1 deletion samples/openapi3/client/petstore/typescript/builds/browser/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:_

Expand All @@ -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);

```
28 changes: 22 additions & 6 deletions samples/openapi3/client/petstore/typescript/builds/browser/configuration.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 4 additions & 2 deletions samples/openapi3/client/petstore/typescript/builds/browser/servers.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
Loading