Skip to main content

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#JavaPHPPythonRubyTSGo
✔️✔️✔️✔️✔️✔️✔️

Change in SDK

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

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)

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#JavaPHPPythonRubyTSGo
✔️✔️✔️✔️✔️✔️✔️

Change in SDK

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

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

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#JavaPHPPythonRubyTSGo
✔️✔️✔️✔️✔️✔️✔️

Change in SDK

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

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

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#JavaPHPPythonRubyTSGo
✔️✔️✔️✔️✔️✔️✔️

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#JavaPHPPythonRubyTSGo
✔️✔️
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:

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

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#JavaPHPPythonRubyTSGo
✔️

Change in SDK

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

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

Use Security Scheme Name For Single Auth

This setting is applicable to those API definitions that contain only 1 auth scheme. By enabling this setting, the authentication interface in the generated SDK client will rely on the scheme name defined in the API definition.

Usage

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

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

Language Support

C#JavaPHPPythonRubyTSGo
✔️✔️✔️✔️✔️✔️✔️

Change in SDK

Configuring this setting has the following effect on the generated SDK with the authentication scheme e.g. Client Credentials Auth scheme, defined in OpenApi specification like:

components:
securitySchemes:
ccg_auth: # <---- arbitrary name
type: oauth2
description: See http://developers.gettyimages.com/api/docs/v3/oauth2.html
flows:
clientCredentials:
tokenUrl: https://api.gettyimages.com/oauth2/token/
scopes: {}
Value Change
true
SdkClient client = new SdkClient.Builder()
.CcgAuth(
new CcgAuthModel.Builder(
"clientId",
"clientSecret"
).Build())
.Build();
false (default)
SdkClient client = new SdkClient.Builder()
.ClientCredentialsAuth(
new ClientCredentialsAuthModel.Builder(
"clientId",
"clientSecret"
).Build())
.Build();

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#JavaPHPPythonRubyTSGo
✔️✔️✔️✔️✔️✔️✔️

Change in SDK

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

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

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#JavaPHPPythonRubyTSGo
✔️✔️
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:

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

Enable Logging

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

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#JavaPHPPythonRubyTSGo
✔️✔️✔️✔️✔️✔️✔️

Change in SDK

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

Value Change
true
SdkClient client = new SdkClient.Builder()
.LoggingConfig(config => config
.LogLevel(LogLevel.Information)
.RequestConfig(reqConfig => reqConfig
.Body(true)
.IncludeHeaders("Content-Type", "Content-Encoding"))
.ResponseConfig(respConfig => respConfig
.Headers(true)
.ExcludeHeaders("X-Powered-By"))
)
.Build();
false (default)
SdkClient client = new SdkClient.Builder()
.Build();

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#JavaPHPPythonRubyTSGo
✔️

Change in SDK

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

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