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​

The Java package name defines the root namespace under which all classes in the generated Java SDK will be organized.

Configuration​

You can configure this setting using one of the following approaches:

  • In the OpenAPI Specification
    Use the x-codegen-settings extension and set the value under the JavaDefaultPackageName key.

  • In the APIMATIC META File
    Set the value under the JavaPackageName field in the CodeGenSettings section.

note

If the setting is defined in both places, the value specified in the APIMatic Metadata File takes precedence.

Usage​

To set a custom Java package name, provide a String value representing the desired root package. This helps organize the SDK structure according to your project's naming conventions and prevents potential naming conflicts. If no value is provided, a default package name is generated based on your API’s Base URI. For example, if the base URI is apimatic.io, the default package name would be io.apimatic.

"info": {
    ...,
    "x-codegen-settings": {
        "JavaDefaultPackageName": "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 post-fixed 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's 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 can't 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 isn't 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 for example 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 won't 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 can't 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.