SDK Interface Customization

These CodeGen settings allow control over the overall look and feel of the generated code.

Project Name

This setting sets the name of the generated SDK package. At times, this change is reflected as client name and sometimes as the interface name, depending on the selected language.

Usage

To use this feature, you need to specify a String value. By default, its value will be your API name.

"info": {
    ...,
    "x-codegen-settings": {
        "ProjectName": "MyProject"
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Change in SDK

Configuring this setting has the following effect on the generated SDK:

C#

Value	Change
Default	Tester.Standard.TesterClient client = new Tester.Standard.TesterClient.Builder() .Environment(Tester.Standard.Environment.Testing) .Port("80") .Suites(SuiteCodeEnum.Hearts) .Build();
Configured	MyProject.Standard.MyProjectClient client = new MyProject.Standard.MyProjectClient.Builder() .Environment(MyProject.Standard.Environment.Testing) .Port("80") .Suites(SuiteCodeEnum.Hearts) .Build();

Java

Value	Change
Default	TesterClient client = new TesterClient.Builder() .httpClientConfig(configBuilder -> configBuilder .timeout(0)) .environment(Environment.TESTING)
Configured	MyProjectClient client = new MyProjectClient.Builder() .httpClientConfig(configBuilder -> configBuilder .timeout(0)) .environment(Environment.TESTING)

PHP

Value	Change
Default	$client = TesterLib\TesterClientBuilder::init() ->environment('testing') ->port('80') ->suites(Models\SuiteCodeEnum::HEARTS)
Configured	$client = MyProjectLib\MyProjectClientBuilder::init() ->environment('testing') ->port('80') ->suites(Models\SuiteCodeEnum::HEARTS);

Python

Value	Change
Default	from tester.tester_client import TesterClient from tester.configuration import Environment client = TesterClient( environment=Environment.TESTING, port = '80', suites = SuiteCodeEnum.HEARTS,)
Configured	from myproject.my_project_client import MyProjectClient from myproject.configuration import Environment client = MyProjectClient( environment=Environment.TESTING, port = '80', suites = SuiteCodeEnum.HEARTS,)

Ruby

Value	Change
Default	client = Tester::Client.new( environment: Environment::TESTING, port: '80', suites: SuiteCodeEnum::HEARTS, )
Configured	client = MyProject::Client.new( environment: Environment::TESTING, port: '80', suites: SuiteCodeEnum::HEARTS, )

Go

Value	Change
Default	config := tester.ConfigurationFactory( tester.WithEnvironment("testing"), tester.WithPort("3000"), tester.WithSuites(4), ) client := tester.NewClient(config)
Configured	config := myproject.ConfigurationFactory( myproject.WithEnvironment("testing"), myproject.WithPort("3000"), myproject.WithSuites(4), ) client := myproject.NewClient(config)

C# Namespace

Enable this setting to use the default value of root namespace in C# SDKs.

Usage

To use this feature, you need to specify a String value. By default, its value will be your API name.

"info": {
    ...,
    "x-codegen-settings": {
        "CSharpNamespace": "OrgNamespace"
    }
}

Language Support

This setting only applies to C# SDKs.

Change in SDK

Configuring this setting has the following effect on the generated SDK:

Value	Change
Default	Tester.Standard.TesterClient client = new Tester.Standard.TesterClient.Builder() .Environment(Tester.Standard.Environment.Testing) .Port("80") .Suites(SuiteCodeEnum.Hearts) .Build();
Configured	OrgNamespace.TesterClient client = new Root.TesterClient.Builder() .Environment(Root.Environment.Testing) .Port("80") .Suites(SuiteCodeEnum.Hearts) .Build();

Java Package Name

This setting sets the default value of the package name to be used in Java SDKs.

Usage

To use this feature, you need to specify a String value. By default, its value will be your Base URI. For example, for base URI apimatic.io, package name would be "io.apimatic".

"info": {
    ...,
    "x-codegen-settings": {
        "JavaPackageName": "Root"
    }
}

Language Support

This setting only applies to Java SDKs.

Change in SDK

Configuring this setting has the following effect on the generated SDK:

Value	Change
Default	Object input = localhost3000.ApiHelper.deserialize("{\"key1\":\"val1\",\"key2\":\"val2\"}");
Configured	Object input = Root.ApiHelper.deserialize("{\"key1\":\"val1\",\"key2\":\"val2\"}");

PHP Namespace

Enable this setting to use the root namespace for PHP SDKs.

Usage

To use this feature, you need to specify a String value. By default, its value will be your API name.

"info": {
    ...,
    "x-codegen-settings": {
        "PHPNamespace": "Apimatic"
    }
}

Language Support

This setting only applies to PHP SDKs.

Change in SDK

Configuring this setting has the following effect on the generated SDK:

Value	Change
Default	$client = TesterLib\TesterClientBuilder::init() ->environment('testing') ->build();
Configured	$client = Apimatic\TesterClientBuilder::init() ->environment('testing') ->build();

Use Controller Prefix

Enabling this setting will postfix each controller class with the word "Controller". For example, a controller class User becomes UserController.

If you want to add a custom prefix, you can enable this setting and use the Controller Postfix setting to set a string value.

Usage

To use this feature, you need to specify a Boolean type. By default, its value is set to true.

"info": {
    ...,
    "x-codegen-settings": {
        "UseControllerPrefix": true
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Change in SDK

Configuring this setting has the following effect on the generated SDK:

C#

Value	Change
true (default)	try { await responseTypesController.GetContentTypeHeadersAsync(); } catch (ApiException e){};
false	try { await responseTypes.GetContentTypeHeadersAsync(); } catch (ApiException e){};

Java

Value	Change
true (default)	responseTypesController.getContentTypeHeadersAsync().thenAccept(result -> { // TODO success callback handler }).exceptionally(exception -> { // TODO failure callback handler return null; });
false	responseTypes.getContentTypeHeadersAsync().thenAccept(result -> { // TODO success callback handler }).exceptionally(exception -> { // TODO failure callback handler return null; });

PHP

Value	Change
true (default)	$responseTypesController->getContentTypeHeaders();
false	$responseTypes->getContentTypeHeaders();

Python

Value	Change
true (default)	result = response_types_controller.get_content_type_headers() print(result)
false	result = response_types.get_content_type_headers() print(result)

Ruby

Value	Change
true (default)	response_types_controller.get_content_type_headers
false	response_types.get_content_type_headers

TypeScript

Value	Change
true (default)	const { result, ...httpResponse } = await responseTypesController.getContentTypeHeaders();
false	const { result, ...httpResponse } = await responseTypes.getContentTypeHeaders();

Go

Value	Change
true (default)	resp, err := ResponseTypesController.GetContentTypeHeaders()
false	resp, err := ResponseTypes.GetContentTypeHeaders()

Controller Postfix

note

To use this feature, make sure you have enabled the Use Controller Prefix setting.

This setting adds a postfix to the Endpoint Group names. For example, an endpoint group is named "User". For a given Controller Postfix value "Api", the name of the endpoint group will become "UserApi". If no value is provided, it will use the default value and become "UserController".

Usage

To use this feature, you need to specify a String value that will be postfixed with the endpoint group name. By default, its value is set to Controller.

"info": {
    ...,
    "x-codegen-settings": {
        "ControllerPostfix": "Api"
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Change in SDK

Configuring this setting has the following effect on the generated SDK:

C#

Value	Change
Default	dynamic result = await echoController.JsonEchoAsync(input);
Configured	dynamic result = await echoApi.JsonEchoAsync(input);

Java

Value	Change
Default	echoController.jsonEchoAsync(input).thenAccept(result -> { // TODO success callback handler }).exceptionally(exception -> { // TODO failure callback handler return null; });
Configured	echoApi.jsonEchoAsync(input).thenAccept(result -> { // TODO success callback handler }).exceptionally(exception -> { // TODO failure callback handler return null; });

PHP

Value	Change
Default	$result = $mEchoController->jsonEcho($input);
Configured	$result = $mEchoApi->jsonEcho($input);

Python

Value	Change
Default	result = echo_controller.json_echo(input)
Configured	result = echo_api.json_echo(input)

Ruby

Value	Change
Default	result = echo_controller.json_echo(input)
Configured	result = echo_api.json_echo(input)

TypeScript

Value	Change
Default	const { result, ...httpResponse } = await echoController.jsonEcho(input);
Configured	const { result, ...httpResponse } = await echoApi.jsonEcho(input);

Go

Value	Change
Default	apiResponse, err := EchoController.JsonEcho(input)
Configured	apiResponse, err := EchoApi.JsonEcho(input)

Controller Namespace

While you have the flexibility to name the controller classes, they must still be organized within the SDK. The controller namespace represents the specific location where the controllers are placed. You can use this setting to specify name of controller namespace in SDKs.

It is recommended to update both the controller postfix and the corresponding controller namespace together.

For example, in Java, you postfix a controller with "Api", so you can use the Controller Namespace setting to place it within a controller namespace called "Apis".

Usage

To use this feature, you need to specify a String value. By default, its value is set to Controller.

"info": {
    ...,
    "x-codegen-settings": {
        "ControllerNamespace": "Apis"
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Generate Interfaces

This setting generates interfaces for controller classes in the generated SDKs. This comes in handy if the SDK users want to write mock tests against the client code in their application.

note

Please note that this setting is experimental and may not work properly at all times. Feel free to contact our support if you run into an issue.

Usage

To use this feature, you need to specify a Boolean value. By default, its value is set to false.

"info": {
    ...,
    "x-codegen-settings": {
        "GenerateInterfaces": false
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
✔️	✔️	❌	❌	❌	❌	➖

note

➖ shows that in Go, this behavior is inherently supported by default where needed and cannot be disabled.

Change in SDK

Configuring this setting has the following effect on the generated SDK:

C#

Value	Change
true	IBodyParamsController bodyParamsController = client.BodyParamsController;
false (default)	BodyParamsController bodyParamsController = client.BodyParamsController;

Java

Value	Change
true	public final class TesterClient implements TesterClientInterface { responseTypes = new DefaultResponseTypesController(globalConfig); formParams = new DefaultFormParamsController(globalConfig); bodyParams = new DefaultBodyParamsController(globalConfig); errorCodes = new DefaultErrorCodesController(globalConfig); }
false (default)	public final class TesterClient implements Configuration { responseTypes = new ResponseTypesController(globalConfig); formParams = new FormParamsController(globalConfig); bodyParams = new BodyParamsController(globalConfig); errorCodes = new ErrorCodesController(globalConfig); }

Client Interface Name

This setting sets the class name of the client library interface. If no value is provided, then default value will be a prefix of the set Project name. For example, if this setting is not configured and your ProjectName is Tester, then the client interface name used throughout the SDK will be TesterClient.

note

Please note that this setting is currently in an experimental phase. We may or may not provide additional support or enhancements for it in the future.

Usage

To use this feature, you need to specify a String value that will be used as a class name in SDKs.

"info": {
    ...,
    "x-codegen-settings": {
        "ClientInterfaceName": "Interface"
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
❌	❌	❌	✔️	❌	❌	❌

Change in SDK

Configuring this setting has the following effect on the generated SDK:

Python

Value	Change
Default	from tester.tester_client import TesterClient from tester.configuration import Environment client = TesterClient( environment=Environment.TESTING, port = '80', suites = SuiteCodeEnum.HEARTS,)
Configured	from tester.interface import Interface from tester.configuration import Environment client = Interface( environment=Environment.TESTING, port = '80', suites = SuiteCodeEnum.HEARTS,)

Do Not Split Words

This setting allows you to specify a list of words that will not split when converting identifiers from API specification to language-specific identifiers. This behavior is valid irrespective of the capitalization of these words. This is useful for declaring brand names such as APIMatic.

The order of words listed determines highest to lowest priority. For example, if you provide the words "apimatic" and "vmware" in your list, APIMaticandVMWare becomes ApimaticAndVmware or apimatic_and_vmware depending on the case used in the SDK language.

note

You can only list words with alphanumeric characters.

Usage

To use this feature, you need to specify a List<string>.

"info": {
    ...,
    "x-codegen-settings": {
        "DoNotSplitWords": ["apimatic", "vmware", "petId"]
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Change in SDK

For "DoNotSplitWords": ["petId"], SDKs will change as follows:

C#

Value	Change
Default	public Models.Pet GetPetById(long petId)
Configured	public Models.Pet GetPetById(long petid)

Java

Value	Change
Default	public Pet getPetById(final long petId)
Configured	public Pet getPetById(final long petid)

PHP

Value	Change
Default	public function getPetById(int $petId): Pet
Configured	public function getPetById(int $petid): Pet

Python

Value	Change
Default	def get_pet_by_id(self, pet_id)
Configured	def get_pet_by_id(self, petid)

Ruby

Value	Change
Default	def get_pet_by_id(pet_id)
Configured	def get_pet_by_id(petid)

TypeScript

Value	Change
Default	async getPetById( petId: bigint, requestOptions?: RequestOptions ): Promise<ApiResponse<Pet>>
Configured	async getPetById( petid: bigint, requestOptions?: RequestOptions ): Promise<ApiResponse<Pet>>

Go

Value	Change
Default	func (p *PetController) GetPetById(petId int64) ( https.ApiResponse[models.Pet], error)
Configured	func (p *PetController) GetPetById(petid int64) ( https.ApiResponse[models.Pet], error)

Synchronous Mode of Code

This setting allows you to switch between synchronous and asynchronous generation of code.

The best practice of code generation is to handle code asynchronously, so this setting is enabled by default. But, you have the option to disable it in case you want the APIMatic CodeGen to generate code synchronously.

Usage

To use this feature, you need to specify a string, either Asynchronous or Synchronous. By default, its value is set to Asynchronous.

"info": {
    ...,
    "x-codegen-settings": {
        "SynchronyMode": "Asynchronous"
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
✔️	✔️	❌	❌	❌	➖	➖

note

➖ shows that in TypeScript and Go, this behavior is inherently supported by default and cannot be disabled.

Change in SDK

Configuring this setting has the following effect on the generated SDK:

C#

Value	Change
Asynchronous (default)	EmployeeComp result = await responseTypesController.ReturnEmployeeModelAsync();
Synchronous	EmployeeComp result = responseTypesController.ReturnEmployeeModel();

Java

Value	Change
Asynchronous (default)	responseTypesController.returnEmployeeModelAsync().thenAccept(result -> { // TODO success callback handler System.out.println(result); }).exceptionally(exception -> { // TODO failure callback handler exception.printStackTrace(); return null; });
Synchronous (default)	try { EmployeeComp result = responseTypesController.returnEmployeeModel(); System.out.println(result); } catch (ApiException e) { e.printStackTrace(); } catch (IOException e) { e.printStackTrace(); }

Enable Logging

By enabling this setting, SDK code generation includes functionality for logging events in the API cycle using a designated library.

note

This is an experimental setting so it might not work in all cases. Please contact our support if you run into an issue.

Usage

To use this feature, you need to specify a Boolean value. By default, its value is set to false.

"info": {
    ...,
    "x-codegen-settings": {
        "EnableLogging": false
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
❌	✔️	❌	❌	❌	❌	❌

Change in SDK

Configuring this setting has the following effect on the generated SDK:

Value	Change
true	TesterClient client = new TesterClient.Builder() .loggingConfig(builder -> builder .level(Level.DEBUG) .logEverything()) .environment(Environment.TESTING) .build();
false (default)	TesterClient client = new TesterClient.Builder() .environment(Environment.TESTING) .build();

Configure Logger

Logger can be configured in the SDK. Follow the steps mentioned in this gist to configure logger for Java client library.

Symbolize Hash Keys in Ruby

Enable this setting to use symbols instead of strings for hash keys in Ruby SDKs.

Usage

To use this feature, you need to specify a Boolean type. By default, its value is set to false.

"info": {
    ...,
    "x-codegen-settings": {
        "SymbolizeHashKeysInRuby": true
    }
}

Language Support

This setting only applies to Ruby SDKs.

Deprecated Settings

We have marked a few of the CodeGen settings as deprecated since we will no longer provide support for them in the future.

Underscore Numbers

Use this setting to add underscores before and after numbers for underscore_case in the generated SDKs.

Usage

To use this feature, you need to specify a Boolean value. By default, its value is set to true.

"info": {
    ...,
    "x-codegen-settings": {
        "UnderscoreNumbers": true
    }
}

Language Support

C#	Java	PHP	Python	Ruby	TS	Go
❌	❌	❌	✔️	❌	❌	❌

Change in SDK

Configuring this setting has the following effect on the generated SDK:

Python

Value	Change
true (default)	result = body_params_controller.update_string_123(value)
false	result = body_params_controller.update_string123(value)