Skip to main content

Model

These CodeGen configurations manage the model-specific behavior in the generated SDKs.

Extended Additional Properties Support

In cases where your OpenAPI specification includes typed additional properties for models, enabling the Extended Additional Properties Support setting ensures that these properties are correctly handled in the generated SDKs. When this option is enabled, models will support typed additional properties, allowing you to define specific data types for additional fields instead of using a generic type.

This feature ensures better alignment with OpenAPI specifications by enabling type safety for additional properties. It also improves consistency, reduces the risk of runtime errors, and provides more flexibility when working with models that include additional, user-defined properties.

Usage

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

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

Language Support

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

Change in SDK

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

Value Change
true
StudentResult body = new StudentResult.Builder(
"student616@oxford.ac.uk"
)
.additionalProperty("Theory Of Automata", 82.1D)
.additionalProperty("Computational complexity", 72.5D)
.additionalProperty("Functional programming", 78.3D)
.build();
false (default)
StudentResult body = new StudentResult.Builder(
"student616@oxford.ac.uk"
)
.build();

Use Model Prefix

Enabling this setting will postfix each model class with the word "Model".

This setting is helpful in cases where in an OpenAPI specification, an API, endpoint, model, controller etc. might have the same name which can lead to confusion. So, to distinguish between them, you can use this setting to specify that it is a model. For example, a model Person becomes PersonModel.

note

Try to use this setting only if there's a chance of naming conflicts in your API specification file.

Usage

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

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

Language Support

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

Change in SDK

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

Value Change
true
CompletableFuture<PersonModel> queryEchoAsync(
final Map<String, Object> queryParameters)
false (default)
CompletableFuture<Person> queryEchoAsync(
final Map<String, Object> queryParameters)

Enable Model Keyword Args in Ruby

This setting determines the usage of keyword arguments for properties in the constructor of models in Ruby SDKs. If enabled, then all parameters are expected to be provided in the argument name along with value during the model instantiation. If disabled, the model constructor expects positional arguments.

Usage

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

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

Language Support

This setting only applies to Ruby SDKs.

Change in SDK

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

Value Change
true
class User
def initialize(name:, email:)
@name = name
@email = email
end
end

user = User.new(email: "bob@example.com", name: "Bob")
false (default)
class User
def initialize(name, email)
@name = name
@email = email
end
end

user = User.new("Alice", "alice@example.com")

Deprecated Settings

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

Enable Additional Model Properties

In cases where your OpenAPI specification holds additional properties of models, you can use this setting to determine whether to include them in the generated SDK or not. Enabling this option allows models to include additional properties in a map structure.

If an endpoint response (with response-type model) contains additional properties that are not part of the model definition, they will be discarded during serialization and deserialization of the model.

note

This setting has been marked as deprecated because it allowed additional properties in model classes to be stored using a generic any type, leaving type management to the user. Use ExtendedAdditionalPropertiesSupport instead.

Usage

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

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

Language Support

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

Generate Models

This setting allows you to choose whether to include models in the generated SDKs and docs or not. You can disable this setting to use maps instead of models.

If you choose to disable this setting, APIMatic CodeGen will not generate any Model related code. Which means, all model related requests and responses will have to be maintained manually.

note

Turning off Model code generation goes against the best practices of writing a client SDK, so we have marked this setting as deprecated.

Usage

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

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

Language Support

C#JavaPHPPythonRubyTSGo
✔️✔️

Enable Immutable Models

This setting determines the immutability of models within the generated SDKs. By enabling this option, the current value of models in the generated SDKs becomes locked, preventing modifications when building requests from your SDK.

note

This setting has been marked as deprecated because, by default, the process of building a request is intended to be flexible. Restricting the values of models is generally regarded as a bad practice, which is why we discourage the use of this setting.

Usage

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

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

Language Support

C#JavaPHPPythonRubyTSGo
✔️✔️

Change in SDK

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

Value Change
true
DeleteBody body = new DeleteBody.Builder("name6", "field0")
.Build()
false (default)
DeleteBody body = new DeleteBody();
body.Name = "name6";
body.Field = "field0";

Ignore If Null JSON

note

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

In the API specification file, a null property is defined as an optional property. But in cases where null is not defined properly, you can enable this setting and the generated SDK will ignore all null properties during JSON serialization of a model.

tip

To avoid using this setting altogether, it is recommended to ensure that your OpenAPI specification file accurately denotes null values as null, optional values as optional, and nullable optional values as such. By following this practice, you can ensure the generation of correct requests across all programming languages.

Usage

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

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

Language Support

C#JavaPHPPythonRubyTSGo
✔️✔️