SDK language options

The language options are used to customize the SDK generation on a per-SDK language basis.

• Generic language options
• C# specific options
• Go specific options
• Java specific options
• PHP specific options
• Python specific options
• Terraform specific options
• TypeScript specific options

Generic language options

These options are applicable to all SDK languages, and are set on a per-language basis in the specific SDK language section. For example, the sdkVersion can be set to different values for each language SDK:

{
    ...
    "languageOptions": {
        "typescript": {
            "sdkVersion": "1.0.0-alpha"
        },
        "python": {
            "sdkVersion": "1.0.0-beta"
        },
        "java": {
            "sdkVersion": "1.0.0-beta-2"
        }
    }
    ...
}

Option	Type	Required	Default	Description
liblabVersion	string	❌	language dependant	The version of liblab SDK generation to use
githubRepoName	string	❌	N/A	The name of the GitHub repository for the SDK
targetBranch	string	❌	main	The branch to create the pull request against
ignoreFiles	array	❌	N/A	A list of files to ignore when generating the SDK
sdkVersion	string	❌	N/A	The version of the SDK
hookDependencies	array	❌	N/A	Additional dependencies for hooks
authors	array	❌	N/A	The authors of the SDK. These values are added to the relevant package manifest. This is not supported for Java SDKs
homepage	string	❌	N/A	The URL for the homepage for this SDK. This is added to the relevant package manifest
additionalConstructorParameters	array	❌	[]	Additional parameters to add to the SDK client constructor. These parameters can then be accessed in hooks.

liblabVersion

Supported SDK languages and versions:

TypeScript v1	TypeScript v2	Java v1	Java v2	Python v1	Python v2	C#	Go	PHP
✅	✅	✅	✅	✅	✅	✅	✅	✅

The liblabVersion setting sets the version of the liblab SDK generation to use.

For example, to use v2 of liblab to generate a Python SDK, use the following:

{
    "languages": [
        "python"
    ],
    "languageOptions": {
        "python": {
            "liblabVersion": "2"
        }
    }
}

The default value of this option depends on the SDK language. These default versions, along with the available versions are documented in our liblab version guide.

Some SDK languages are only available in certain versions of liblab, whereas others might be available in multiple versions and you can use this option to determine which version to use.

If an SDK language is added in a later version, then setting an earlier version will default to the first version that supports that language. For example, C# is added in liblab version 2, so setting this to 1:

{
    "languages": [
        "csharp"
    ],
    "languageOptions": {
        "csharp": {
            "liblabVersion": "1"
        }
    }
}

Will be the equivalent of setting it to 2.

You can read more on the supported liblab versions and the capabilities of SDKs using these versions in our liblab version guide.

githubRepoName

Supported SDK languages and versions:

TypeScript v1	TypeScript v2	Java v1	Java v2	Python v1	Python v2	C#	Go	PHP
✅	✅	✅	✅	✅	✅	✅	✅	✅

The githubRepoName setting sets the name of the GitHub repository for this SDK. This is used by the liblab pr command to create a pull request for the SDK into that repo. You can read more about this in the liblab pr section of the liblab CLI documentation.

note

It's also used in Java v2 SDKs to fill in scm information in the pom.xml file, required when publishing to Maven Central.

targetBranch

Supported SDK languages and versions:

TypeScript v1	TypeScript v2	Java v1	Java v2	Python v1	Python v2	C#	Go	PHP
✅	✅	✅	✅	✅	✅	✅	✅	✅

The targetBranch setting sets the branch in GitHub for this SDK in the repo defined in the githubRepoName setting. This is used by the liblab pr command to create a pull request for the SDK into that branch. You can read more about this in the liblab pr section of the liblab CLI documentation.

note

It's also used in Java SDKs to fill in scm information in the pom.xml file, required when publishing to Maven Central.

ignoreFiles

Supported SDK languages and versions:

TypeScript v1	TypeScript v2	Java v1	Java v2	Python v1	Python v2	C#	Go	PHP
✅	✅	✅	✅	✅	✅	✅	✅	✅

This option allows you to specify a list of files to ignore when generating the SDK. This is useful if you want to exclude files that are generated by the SDK generator. For example, if you want to completely customize the README or package manifest files.

For example, if you want to create a custom README file for your SDK that is not replaced during SDK generation, set this value to README.md:

TypeScript v1

{
    ...
    "languageOptions": {
        "typescript": {
            "ignoreFiles": [
                "README.md"
            ]
        }
    }
    ...
}

TypeScript v2

{
    ...
    "languageOptions": {
        "typescript": {
            "ignoreFiles": [
                "README.md"
            ]
        }
    }
    ...
}

Java v1

{
    ...
    "languageOptions": {
        "java": {
            "ignoreFiles": [
                "README.md"
            ]
        }
    }
    ...
}

Java v2

{
    ...
    "languageOptions": {
        "java": {
            "ignoreFiles": [
                "README.md"
            ]
        }
    }
    ...
}

Python v1

{
    ...
    "languageOptions": {
        "python": {
            "ignoreFiles": [
                "README.md"
            ]
        }
    }
    ...
}

Python v2

{
    ...
    "languageOptions": {
        "python": {
            "ignoreFiles": [
                "README.md"
            ]
        }
    }
    ...
}

C#

{
    ...
    "languageOptions": {
        "csharp": {
            "ignoreFiles": [
                "README.md"
            ]
        }
    }
    ...
}

Go

{
    ...
    "languageOptions": {
        "go": {
            "ignoreFiles": [
                "README.md"
            ]
        }
    }
    ...
}

PHP

{
    ...
    "languageOptions": {
        "php": {
            "ignoreFiles": [
                "README.md"
            ]
        }
    }
    ...
}

This is an array, so you can specify as many files as you need.

sdkVersion

Supported SDK languages and versions:

TypeScript v1	TypeScript v2	Java v1	Java v2	Python v1	Python v2	C#	Go	PHP
✅	✅	✅	✅	✅	✅	✅	❌1	❌

¹ Go does not have a package manifest file for this version to be written to. This version is written to the README.md file, and you will need to manually use it when you create a release of your SDK inside you GitHub repository.

The sdkVersion setting sets the version of the SDK in the relevant file. For example, for Python SDKs, this is set in the pyproject.toml file, for TypeScript this is set in the project.json file.

This version should be using semver to ensure it is compatible with the different package managers. TypeScript has some limitations on what is supported, so any labels (such as alpha in 0.9.3-alpha) will be stripped out.

For example, with these options:

{
    ...
    "languageOptions": {
        "typescript": {
            "sdkVersion": "1.0.0-alpha"
        }
    }
    ...
}

The TypeScript project.json file will look like:

{
    "version": "1.0.0"
}

Whereas the Python pyproject.toml file will look like:

[project]
version = "1.0.0-alpha"

hookDependencies

Supported SDK languages and versions:

TypeScript v1	TypeScript v2	Java v1	Java v2	Python v1	Python v2	C#	Go	PHP
✅	✅	✅	✅	✅	✅	❌	❌	✅

When you create hooks, you can define the dependencies for those hooks in the relevant hooks folder (such as in the requirements.txt for Python hooks). If you need to add additional dependencies, you can add them here and they will be added to the SDKs.

note

This should only be used if there is a reason you cannot add the dependency to the hook code directly. It is best practice to add them there.

This is an array of objects, with each object having the following options:

Option	Type	Required	Default	Description
name	string	✅	N/A	The name of the dependency
version	string	✅	N/A	The version of the dependency
groupId	string	❌	N/A	The groupId of the hook dependency for Java hooks

name

The name field is the name of the package that needs to be included in the dependencies. This is the same name you would use with the relevant packaging tool to install the package, such as npm install or pip install.

For example, to include the Python python-dotenv package, you would use:

{
  ...
  "languageOptions": {
    "python": {
      "hookDependencies": [
        {
          "name": "python-dotenv",
          "version": "1.0.0"
        }
      ]
    }
  }
  ...
}

version

The version field defines the version to add to the dependencies.

For example, to include the TypeScript pad-left package fixed at version 1.0.2 you would use:

{
  ...
  "languageOptions": {
    "typescript": {
      "hookDependencies": [
        {
          "name": "pad-left",
          "version": "1.0.2"
        }
      ]
    }
  }
  ...
}

groupId

The groupId setting is used for Java packages only, and allows you to define the groupId for the hook dependency.

authors

Supported SDK languages and versions:

TypeScript v1	TypeScript v2	Java v1	Java v2	Python v1	Python v2	C#	Go	PHP
✅	✅	❌	❌	✅	❌	✅	❌	❌

The authors option sets the list of authors of the SDK in the relevant package manifest. This is an array of objects containing the authors name, and optionally their email.

TypeScript v1

The author is set in the package.json file in the SDK.

For example, setting:

{
    ...
    "languageOptions": {
        "typescript": {
            "authors": [
                {
                    "name": "Llama Soda",
                    "email": "[email protected]"
                }
            ]
        }
    }
    ...
}

will give a package.json file with:

{
    ...
    "author": "Llama Soda <[email protected]>",
    ...
}

note

Only one author is supported for TypeScript v1. If you set multiple authors for TypeScript, only the first one is used.

TypeScript v2

{
    ...
    "languageOptions": {
        "typescript": {
            "authors": [
                {
                    "name": "Llama Soda",
                    "email": "[email protected]"
                }
            ]
        }
    }
    ...
}

Java v1

This feature is not supported by Java v1 SDKs.

Java v2

This feature is not supported by Java v2 SDKs. Use the Java specific developers option instead.

Python v1

The authors are set in the pyproject.toml file in the SDK. For example, setting:

{
    ...
    "languageOptions": {
        "python": {
            "authors": [
                {
                    "name": "Llama Soda",
                    "email": "[email protected]"
                },
                {
                    "name": "Llama Boba",
                    "email": "[email protected]"
                }
            ]
        }
    }
    ...
}

will give a pyproject.toml file with:

[project]
authors = [
  { name="Llama Soda", email="[email protected]" },
  { name="Llama Boba", email="[email protected]" }
]
...

Python v2

This feature is not currently supported with Python v2 SDKs.

C#

The authors names are added to the Authors property in the .csproj file for the SDK as a comma separated list. Emails are not supported for C# SDKs.

For example, setting:

{
    ...
    "languageOptions": {
        "csharp": {
            "authors": [
                {
                    "name": "Exciting Soda API Team"
                },

                {
                    "name": "Exciting Soda SDK Team"
                }
            ]
        }
    }
    ...
}

will give a .csproj file with:

  <PropertyGroup>
    ...
    <Authors>Exciting Soda API Team, Exciting Soda SDK Team</Authors>
  </PropertyGroup>

Go

This feature is not currently supported with Go SDKs.

PHP

This feature is not currently supported with PHP SDKs.

Option	Type	Required	Default	Description
name	string	✅	N/A	The name of the author
email	string	❌	N/A	The email address of the author

name

The name field is the name of the author.

email

The email field defines the email address of the author. This field is optional.

homepage

Supported SDK languages and versions:

TypeScript v1	TypeScript v2	Java v1	Java v2	Python v1	Python v2	C#	Go	PHP
✅	❌	✅	✅	✅	❌	✅	❌	❌

The homepage option sets the homepage of the SDK in the relevant package manifest. This needs to be a valid URL.

TypeScript v1

The homepage is set in the package.json file in the SDK. For example, setting:

{
    ...
    "languageOptions": {
        "typescript": {
            "homepage": "https://exciting.soda"
        }
    }
    ...
}

will give a package.json file with:

{
    ...
    "homepage": "https://exciting.soda",
    ...
}

TypeScript v2

This feature is not currently supported with TypeScript v2 SDKs.

Java v1

The homepage is set in the pom.xml file in the SDK. For example, setting:

{
    ...
    "languageOptions": {
        "java": {
            "homepage": "https://exciting.soda"
        }
    }
    ...
}

will give a pom.xml file with:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    ...
    <organization>
        <url>https://exciting.soda</url>
    </organization>
</project>

Java v2

The homepage is set in the pom.xml file in the SDK. For example, setting:

{
    ...
    "languageOptions": {
        "java": {
            "homepage": "https://exciting.soda"
        }
    }
    ...
}

will give a pom.xml file with:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    ...
    <url>https://exciting.soda</url>
</project>

Python v1

The homepage is set in the pyproject.toml file in the SDK. For example, setting:

{
    ...
    "languageOptions": {
        "python": {
            "homepage": "https://exciting.soda"
        }
    }
    ...
}

will give a pyproject.toml file with:

[project.urls]
Homepage = "https://exciting.soda"

Python v2

This feature is not currently supported in Python v2 SDKs.

C#

The authors names are added to the ProjectUrl property in the .csproj file for the SDK. For example, setting:

{
    ...
    "languageOptions": {
        "csharp": {
            "homepage": "https://exciting.soda"
        }
    }
    ...
}

will give a .csproj file with:

  <PropertyGroup>
    ...
    <ProjectUrl>https://exciting.soda</ProjectUrl>
  </PropertyGroup>

Go

This feature is not currently supported with Go SDKs.

PHP

This feature is not currently supported with PHP SDKs.

additionalConstructorParameters

Supported SDK languages and versions:

TypeScript v1	TypeScript v2	Java v1	Java v2	Python v1	Python v2	C#	Go	PHP
❌	✅	✅	✅	❌	✅	❌	✅	✅

The additionalConstructorParameters option allows you to specify additional parameters that will be added to the SDK client constructor. These parameters can then be accessed from hooks.

This is an array of objects, with each object having the following properties:

Option	Type	Required	Default	Description
name	string	✅	N/A	The name of the parameter
example	string	❌	N/A	An example value for the generated documentation

These parameters will be added to the SDK client constructor either directly, or via a config object depending on the SDK language.

TypeScript v1

Additional constructor parameters are not supported in v1 of the TypeScript SDK generation.

TypeScript v2

For example, if you wanted to define a client Id and client secret for oAuth that is used by your custom hooks code to authenticate requests, you could set this option in your config file like this:

{
    ...
    "languageOptions": {
        "typescript": {
            "additionalConstructorParameters": [
                {
                    "name": "client-id",
                    "example": "myClientId"
                },
                {
                    "name": "client-secret",
                    "example": "an-example-client-secret"
                }
            ]
        }
    }
    ...
}

This would add the following parameters to the SDK client constructor config parameter:

class SDKName {
    constructor(
        config: {
            ...
            clientId?: string;
            clientSecret?: string;
        },
        ...
    ) {
    ...
    }

}

These parameters are passed to the params parameter of the hooks beforeRequest, afterResponse, and onError methods. For example, in the beforeRequest method:

export class CustomHook implements Hook {
  beforeRequest(request: HttpRequest, params: Map<string, string>): HttpRequest {
    // Get the client Id and secret from the params
    const clientId = params.get("clientId");
    const clientSecret = params.get("clientSecret");
    if(!clientId || !clientSecret) {
      throw new Error("clientId and clientSecret are required");
    }
    return request;
  }
}

Java v1

For example, if you wanted to define a client Id and client secret for oAuth that is used by your custom hooks code to authenticate requests, you could set this option in your config file like this:

{
    ...
    "languageOptions": {
        "java": {
            "additionalConstructorParameters": [
                {
                    "name": "clientId",
                    "example": "myClientId"
                },
                {
                    "name": "clientSecret",
                    "example": "myClientSecret"
                }
            ]
        }
    }
    ...
}

This would add the following methods to the SDK client config builder:

TestSdkConfig config = TestSdkConfig
      .builder()
      .clientId("example")
      .clientSecret("example")
      ...
      .build();

TestSdk testSdk = new TestSdk(config);

These parameters are passed to the additionalParameters parameter of the hooks beforeRequest, afterResponse, and onError methods. For example, in the beforeRequest method, you could access these parameters like this:

public class CustomHook implements Hook {
  @Override
  public Request beforeRequest(Request request, Map<String, String> additionalParameters) {
    String clientId = additionalParameters.get("clientId");
    String clientSecret = additionalParameters.get("clientSecret");

    if (clientId == null || clientId.isEmpty() || clientSecret == null || clientSecret.isEmpty()) {
        throw new IllegalArgumentException("Client ID and/or Client Secret is either not defined or is empty.");
    }
    return request;
  }

  @Override
  public Response afterResponse(
      Request request, Response response, Map<String, String> additionalParameters) {
    return response;
  }

  @Override
  public void onError(
      Request request, Exception exception, Map<String, String> additionalParameters) {}
}

Java v2

For example, if you wanted to define a client Id and client secret for oAuth that is used by your custom hooks code to authenticate requests, you could set this option in your config file like this:

{
    ...
    "languageOptions": {
        "java": {
            "additionalConstructorParameters": [
                {
                    "name": "clientId",
                    "example": "myClientId"
                },
                {
                    "name": "clientSecret",
                    "example": "myClientSecret"
                }
            ]
        }
    }
    ...
}

This would add the following fields to the SDK's config class:

public class MySdkConfig {
  ...
  private String clientId;
  private String clientSecret;
}

These can then be set when creating the SDK client:

MySdkConfig config = MySdkConfig.builder()
  .clientId("myClientId")
  .clientSecret("myClientSecret")
  .build();

MySdk client = new MySdk(config);

These parameters are passed to the additionalParameters parameter of the hooks beforeRequest, afterResponse, and onError methods. This parameter is a Map<String, String>, with the keys matching the name of the additional constructor parameters. For example, in the beforeRequest method, you could access these parameters like this:

@Override
public Request beforeRequest(Request request, Map<String, String> additionalParameters) {
  // Get the client Id and secret from the additional constructor parameters
  String clientId = additionalParameters.get("clientId");
  String clientSecret = additionalParameters.get("clientSecret");

  // Do something with the client id and secret
  ...

  return request;
}

Python v1

Additional constructor parameters are not supported in v1 of the Python SDK generation.

Python v2

For example, if you wanted to define a client Id and client secret for oAuth that is used by your custom hooks code to authenticate requests, you could set this option in your config file like this:

{
    ...
    "languageOptions": {
        "python": {
            "additionalConstructorParameters": [
                {
                    "name": "client_id",
                    "example": "myClientId"
                },
                {
                    "name": "client_secret",
                    "example": "myClientSecret"
                }
            ]
        }
    }
    ...
}

This would add the following parameters to the SDK client constructor:

class MyClient:
    def __init__(
        self,
        client_id: str = None,
        client_secret: str = None,
    ):

These parameters are passed to the kwargs parameter of the hooks before_request, after_response, and on_error methods. For example, in the before_request method, you could access these parameters like this:

def before_request(self, request: Request, **kwargs):
    # Get the client Id and secret from the kwargs
    client_id = kwargs.get("client_id")
    client_secret = kwargs.get("client_secret")

C#

This feature is not currently supported with C# SDKs.

Go

For example, if you wanted to define a client Id and client secret for oAuth that is used by your custom hooks code to authenticate requests, you could set this option in your config file like this:

{
    ...
    "languageOptions": {
        "go": {
            "additionalConstructorParameters": [
                {
                    "name": "ClientId",
                    "example": "myClientId"
                },
                {
                    "name": "ClientSecret",
                    "example": "myClientSecret"
                }
            ]
        }
    }
    ...
}

This would add the following to the config struct:

type Config struct {
    ...
    ClientId     *string
    ClientSecret *string
}

func (c *Config) SetClientId(clientId string) {
    c.ClientId = &clientId
}

func (c *Config) GetClientId() string {
    return *c.ClientId
}

func (c *Config) SetClientSecret(clientSecret string) {
    c.ClientSecret = &clientSecret
}

func (c *Config) GetClientSecret() string {
    return *c.ClientSecret
}

This is then passed to the SDK client constructor:

config := mysdkconfig.NewConfig()
config.SetClientId(clientId)
config.SetClientSecret(clientSecret)

client := mysdk.NewMySDK(config)

These parameters are passed to the params parameter of the hooks BeforeRequest, AfterResponse, and OnError methods. This parameter is a map of key/value pairs, with the keys matching the name of the additional constructor parameters. For example, in the BeforeRequest method, you could access these parameters like this:

func (h *CustomHook) BeforeRequest(req Request, params map[string]string) Request {
    // Get the client id and secret from the hook parameters
    clientId := params["ClientId"]
    clientSecret := params["ClientSecret"]

    // Do something with the client id and secret
    ...

    return req
}

PHP

For example, if you wanted to define a client Id and client secret for oAuth that is used by your custom hooks code to authenticate requests, you could set this option in your config file like this:

{
    ...
    "languageOptions": {
        "php": {
            "additionalConstructorParameters": [
                {
                    "name": "clientId",
                    "example": "myClientId"
                },
                {
                    "name": "clientSecret",
                    "example": "myClientSecret"
                }
            ]
        }
    }
    ...
}

This would add the following to the SDK client constructor:

class Client
{
    public function __construct(
        string $clientId = '',
        string $clientSecret = ''
    )
}

These parameters are passed to the params parameter of the hooks Constructor method. This parameter is an array of key/value pairs, with the keys matching the name of the additional constructor parameters. For example, you could access these parameters like this:

public function __construct(array $params)
{
    $clientId = $params['clientId'];
    $clientSecret = $params['clientSecret'];
}

C# specific options

These options are specific to the C# SDKs.

Option	Type	Required	Default	Description
packageId	string	❌	N/A	The NuGet package Id to set for the C# SDK project

packageId

The packageId setting sets the NuGet package Id that will be used for the generated SDK project. This will be used as the package identifier that is used across the relevant NuGet gallery.

For example, with this option:

{
    ...
    "languageOptions": {
        "csharp": {
            "packageId": "Exciting.Soda"
        }
    }
    ...
}

You will get a .csproj file with the package Id set like this:

<PropertyGroup>
  <PackageId>Exciting.Soda</PackageId>
</PropertyGroup>

Go specific options

These options are specific to the Go SDKs.

Option	Type	Required	Default	Description
goModuleName	string	✅	N/A	The Go module to use for the SDK

goModuleName

The goModuleName setting sets the Go module to use for the SDK. This is set in the go.mod file, and is used when publishing the SDK to Go.

For example, with these options:

{
    ...
    "languageOptions": {
        "go": {
            "goModuleName": "github.com/excitingsoda/sdk"
        }
    }
    ...
}

You will get a go.mod file that looks like:

module github.com/excitingsoda/sdk

This should conform to the Go module naming rules.

note

If you are generating a Terraform provider, you will also need to set this value regardless of whether you are also generating a Go SDK. The Terraform provider contains an internal Go SDK used to interact with your API that needs this module name. This value must be different than the Terraform provider's providerGoModuleName option.

Java specific options

These options are specific to the Java SDKs.

Option	Type	Required	Default	Description
groupId	string	❌	N/A	The Maven group ID to use for the SDK
artifactId	string	❌	N/A	The Maven artifact ID to use for the SDK
developers	array	❌	N/A	The developers to reference in the pom.xml

note

artifactId and developers only apply to Java v2 SDKs. For Java v1 SDKs, these options are ignored.

groupId

The groupId is used to set the groupId used by the Java SDK. This is set as the groupId in the pom.xml file, as well as being used to define the namespace for the SDK classes.

For example, with these options:

{
    ...
    "languageOptions": {
        "java": {
            "groupId": "soda.exciting"
        }
    }
    ...
}

You would get this in the pom.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <groupId>soda.exciting</groupId>
  ...
</project>

The package name for the SDK would be soda.exciting. In the output folder you would have src/main/java/soda/exciting, and the classes would be in the soda.exciting namespace:

package soda.exciting;

If this is not set, the groupId will default to either the first entry in environments, or to baseURL if this is set, or to the first entry in the servers list in the spec, in this order of priority, in reverse domain format.

note

If you also release other Java packages then it is recommended that you set the groupId to a specific Id for this SDK instead of just relying on the defaults. This will reduce the chance of your customers having clashes with split packages.

artifactId

The artifactId is used to set the artifactId used by the Java SDK. This is set as the artifactId in the pom.xml file.

For example, with these options:

{
    ...
    "languageOptions": {
        "java": {
            "artifactId": "exciting-soda"
        }
    }
    ...
}

You would get this in the pom.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <artifactId>exciting-soda</artifactId>
  ...
</project>

If this is not set, the artifactId will default to the kebab-cased version of sdkName.

developers

The developers array is used to define the developers' information to set in the pom.xml file.

note

Having at least one developer is a requirement for publishing to Maven Central. See https://central.sonatype.org/publish/requirements/#developer-information

Option	Type	Required	Default	Description
name	string	✅	N/A	The developer's name
email	string	✅	N/A	The developer's email
organization	string	✅	N/A	The developer's organization
organizationUrl	string	✅	N/A	The developer's organization url

name

The developer's name.

email

The developer's email.

organization

The developer's organization.

organizationUrl

The developer's organization url. This can also be your profile to GitHub or other forges.

PHP specific options

These options are specific to the PHP SDKs.

Option	Type	Required	Default	Description
packageName	string	✅	N/A	The name of the Composer package to publish to

packageName

The packageName setting sets the name of the Composer package. This is set in the composer.json file, and is used when publishing the SDK to PHP repositories like Packagist.

It must be in the format vendor/package, where vendor is the name of your organization (e.g. exciting-soda), and package is the name of the package (e.g. sdk). It must not have any spaces or capital letters. For example, with these options:

json
{
    ...
    "languageOptions": {
        "php": {
            "packageName": "exciting-soda/sdk"
        }
    }
    ...
}

You will get a composer.json file that looks like:

json
{
    "name": "exciting-soda/sdk",
    ...
}

Python specific options

These options are specific to the Python SDKs.

Option	Type	Required	Default	Description
pypiPackageName	string	❌	N/A	The name of the PyPI package to publish to
alwaysInitializeOptionals	bool	❌	true	Should optional parameters always be initialized?
classifiers	array	❌	true	The classifiers to set in the pyproject.toml
projectUrls	object	❌	true	A list of project URLs to add to the pyproject.toml file
strictVersion	bool	❌	false	Enforce strict dependency versions be generated
enforceRequestValidation	bool	❌	false(v1), true(v2)	If requests are sent as dictionaries instead of models, should they be validated for all mandatory fields

pypiPackageName

Supported Python SDK generation versions:

Python v1	Python v2
✅	✅

The pypiPackageName setting sets the name of the PyPI package to publish to. This is set in the pyproject.toml file, and is used when publishing the SDK to PyPI.

For example, with these options:

{
    ...
    "languageOptions": {
        "python": {
            "pypiPackageName": "exciting-soda"
        }
    }
    ...
}

You will get a pyproject.toml file that looks like:

[project]
name = "exciting-soda"

alwaysInitializeOptionals

Supported Python SDK generation versions:

Python v1	Python v2
✅	✅

By default, optional parameters that are not set on a request object, or received on a response object are set to None. This is the default behavior for Python, and is the recommended way to handle optional parameters. If you have a reason for not initializing anything that is not set, then set this option to false.

For example, if this is set to true (the default), a request object will look something like this:

class SodaRequest(BaseModel):
  def __init__(
    self,
    id: int,
    name: str = None,
    flavor: str = None,
    **kwargs,
  ):
    self.id = id

    self.name = name
    self.flavor = flavor

If this is set to false, you would get:

class SodaRequest(BaseModel):
  def __init__(
    self,
    id: int,
    name: str = None,
    flavor: str = None,
    **kwargs,
  ):
    self.id = id

    if name is not None:
      self.name = name
    if flavor is not None:
      self.flavor = flavor

This may be preferred depending on what your API is expecting.

classifiers

Supported Python SDK generation versions:

Python v1	Python v2
✅	✅

The classifiers setting sets the PyPI Trove classifiers that will be set in the pyproject.toml file. This is an array of strings, with each string being a classifier that will be added.

For example, setting this:

{
    ...
    "languageOptions": {
        "python": {
            "classifiers": [
                "Development Status :: 3 - Alpha",
                "Programming Language :: Python :: 3.9"
            ]
        }
    }
    ...
}

Will give a pyproject.toml file that looks like:

[project]
classifiers = [
  "Development Status :: 3 - Alpha",
  "Programming Language :: Python :: 3.9"
]
...

projectUrls

Supported Python SDK generation versions:

Python v1	Python v2
❌	✅

The projectUrls setting sets the URLs for the project in the pyproject.toml file. This is an object, with each key being the name of the URL, and the value being the URL itself.

For example, setting this:

{
    ...
    "languageOptions": {
        "python": {
            "projectUrls": {
                "Homepage": "https://exciting.soda",
                "Documentation": "https://exciting.soda/docs"
            }
        }
    }
    ...
}

Will give a pyproject.toml file that looks like:

[project.urls]
Homepage = "https://exciting.soda"
Documentation = "https://exciting.soda/docs"

strictVersion

Supported Python SDK generation versions:

Python v1	Python v2
✅	❌

The strictVersion setting sets whether or not to enforce strict dependency versions in the generated requirements.txt (Python v1) and pyproject.toml (Python v1 and v2) files. If this is set to true, then the SDK will use the exact version of the dependency. If this is set to false, then the SDK will use the minimum version of the dependency.

This applies to both the dependencies from the generated SDK, and any dependencies set in any custom hooks you have written.

For example, if this is set to false, or not set, then the generated dependency files will look like this:

pyproject.toml

requests
http-exceptions
pytest
responses

requirements.txt (v1 only)

[project]
dependencies = [
    "requests",
    "http-exceptions",
    "pytest",
    "responses"
]
...

If this is set to true, then the generated files will have the versions set:

pyproject.toml

requests==2.31.0
http-exceptions==0.2.10
pytest==7.1.2
responses==0.21.0

requirements.txt (v1 only)

[project]
dependencies = [
    "requests==2.31.0",
    "http-exceptions==0.2.10",
    "pytest==7.1.2",
    "responses==0.21.0"
]
...

note

From v2 onwards, liblab will only generate a pyproject.toml file and not a requirements.txt file.

enforceRequestValidation

Supported Python SDK generation versions:

Python v1	Python v2
✅	✅

When a Python SDK is generated, models are created for the requests and responses made, providing strong typing for your API. Python SDKs also support passing dictionaries instead of models. If a dictionary is passed, the enforceRequestValidation flag determines if that dictionary is validated against the expected properties for the request in the SDK, or if it is left to the API.

For SDKs generated using Python v1 (liblabVersion set to "1), the default value is false. For SDKs generated using Python v2 (liblabVersion set to "2), the default value is true.

Setting enforceRequestValidation to true will validate in the SDK, setting it to false will not.

For example, if you have the following schema in you spec:

MessageRequest:
  type: object
  properties:
    name:
      type: string
      description: The message name
    content:
      type: string
      description: The contents of the message.
  required:
    - name
    - content

A MessageRequest object will be generated in the SDK:

class MessageRequest(BaseModel):
    def __init__(self, content: str, name: str, **kwargs):
        self.content= content
        self.name= name

When you call the SDK, you can either pass this request object:

request = MessageRequest(name="Greeting", content="This soda is exciting!")
message_service.create_message(request)

Or you can pass a dictionary:

request = {"name":"Greeting", "content":"This soda is exciting!"}
message_service.create_message(request)

If you pass a dictionary, then it is easier to make a mistake and not pass the required properties. For example, in this case you might set the "message" property instead of "content":

# message is the wrong property name, it should be content
request = {"name":"Greeting", "message":"This soda is exciting!"}
message_service.create_message(request)

If enforceRequestValidation is set to true and you pass this dictionary, then the SDK will create a MessageRequest for you from the dictionary values, and raise an exception if any required properties are missing:

TypeError: MessageRequest.__init__() got an unexpected keyword argument 'message'

If enforceRequestValidation is set to false then the dictionary is passed to the API as is, and the API will need to validate the data.

Only required properties are validated.

Terraform specific options

These options are specific to Terraform providers.

Option	Type	Required	Default	Description
providerName	string	✅	N/A	The name of the Terraform provider. This must be in kebab-case.
providerVersion	string	✅	N/A	The version of the Terraform provider. This must be in semver format.
providerGoModuleName	string	✅	N/A	The name of the Go module to use for the Terraform provider.
providerSchemaConfig	object	❌	{ "addressKey": "host", "authTokenKey": "auth_token" }	Customization for keys in the Terraform provider configuration.
mockAcceptance	bool	❌	false	Should the generated Terraform provider tests use a mock server or not?
hideComputedDiff	bool	❌	false	Hide computed values on updates

providerName

This is the name of the Terraform provider, and must be in kebab-case.

For example, with these options:

{
    ...
    "languageOptions": {
        "terraform": {
            "providerName": "exciting-soda-provider",
        }
    }
    ...
}

You will get a provider.go file that contains the following:

func (p *Provider) Metadata(ctx context.Context,
                            req provider.MetadataRequest,
                            resp *provider.MetadataResponse) {
    resp.TypeName = "exciting-soda-provider"
    ...
}

Which will result in your end customers main.tf:

provider "exciting-soda-provider" {
  host = "https://api.soda.com"
  auth_token = "soda_MyToken123"
}

providerVersion

This is the version of the Terraform provider, and must be in semver format.

For example, with these options:

{
    ...
    "languageOptions": {
        "terraform": {
            "providerVersion": "1.7.2"
        }
    }
    ...
}

You will get a provider.go file that contains the following:

func (p *Provider) Metadata(ctx context.Context, 
                            req provider.MetadataRequest, 
                            resp *provider.MetadataResponse) {
    resp.Version = "1.7.2"
    ...
}

Which will result in your end customers main.tf:

terraform {
  required_providers {
    exciting-soda = {
      source  = "hashicorp.com/exciting-soda"
      version = "1.7.2"
    }
  }
}

providerGoModuleName

This is the name of the Go module to use for the Terraform provider. This is set in the go.mod file, and is used when publishing the Terraform provider.

For example, with these options:

{
    ...
    "languageOptions": {
        "terraform": {
            "providerGoModuleName": "github.com/excitingsoda/provider"
        }
    }
    ...
}

You will get a go.mod file in your Terraform provider that looks like:

module github.com/excitingsoda/provider

This should conform to the Go module naming rules, and must be different to the goModuleName option in the Go language options.

note

The Terraform provider is a Go module that wraps an internal Go SDK used to interact with your API. This means that you will need to set the goModuleName option for the Go SDK as well as the providerGoModuleName option for the Terraform provider. These 2 values must be different.

providerSchemaConfig

This option provides options to customize how your Terraform provider schema is generated. This is an object with the following options:

Option	Type	Required	Default	Description
addressKey	string	❌	host	The key to use for the server url field in the provider schema
authTokenKey	string	❌	auth_token	The key to use for the auth token field in the provider schema

For example, with these options:

{
    ...
    "languageOptions": {
        "terraform": {
            "providerSchemaConfig": {
                "addressKey": "url",
                "authTokenKey": "token"
            }
        }
    }
    ...
}

The generated provider schema will look like this:

func (p *Provider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) {
    resp.Schema = schema.Schema{
        Attributes: map[string]schema.Attribute{
            "url": schema.StringAttribute{
                ...
            },
            "token": schema.StringAttribute{
                ...
            },
        },
    }
}

Which will result in your end customers main.tf:

provider "exciting-soda" {
    url = "https://api.soda.com"
    token = "soda_MyToken"
}

Since this is an optional field - you can omit it. The default behavior is:

provider "exciting-soda" {
    host = "https://api.soda.com"
    auth_token = "soda_MyToken"
}

mockAcceptance

When a Terraform provider is generated, liblab will also generate end-to-end acceptance tests for the provider. These tests will call your API to ensure that the provider is working as expected.

The mockAcceptance setting determines whether or not to use a mock server for the Terraform provider acceptance tests. If this is set to true, then a mock server will be used. If this is set to false, then the actual API will be used.

hideComputedDiff

When generating a plan for a resource, there will be values that are computed on the server (e.g. id or createdAt). Terraform shows the following value on terraform plan in such cases, for example id = (known after apply).

When generating a plan for updates, setting this value to true hides the computed values in the update.

This does not apply to create, when all computed values are required to be shown.

warning

Some computed values are computed even on updates (e.g. updateAt). Setting this flag to true will cause errors when generating the plan. If you have such fields, please mark them with x-liblab-show-diff: true.

TypeScript specific options

These options are specific to the TypeScript SDKs.

Option	Type	Required	Default	Description
npmOrg	string	❌	N/A	The npm organization to publish to
npmName	string	❌	N/A	The npm package name to publish to
httpClient	string	❌	fetch	The HTTP client to use
bundle	bool	❌	false	Should the SDKs be bundled
exportClassDefault	bool	❌	false	Should the SDK export the main class as default

npmOrg

Supported TypeScript SDK generation versions:

TypeScript v1	TypeScript v2
✅	✅

The npmOrg setting sets the scope for the npm package name.

For example, with these options:

{
    ...
    "languageOptions": {
        "typescript": {
            "npmOrg": "exciting",
            "npmName": "soda"
        }
    }
    ...
}

You will get a package.json file that looks like:

{
    "name": "@exciting/soda",
    ...
}

Set this to your organization name if you want to publish the SDK to your organization's npm account.

npmName

Supported TypeScript SDK generation versions:

TypeScript v1	TypeScript v2
✅	✅

The npmName setting sets the npm package name, scoped with the npmOrg if this is set. For example6, if you set the npmOrg to exciting, and the npmName to soda, the SDK will be published to @exciting/soda.

Set this to your package name if you want to publish the SDK to your npm account.

httpClient

Supported TypeScript SDK generation versions:

TypeScript v1	TypeScript v2
✅	✅

Sets the HTTP client to use for the SDK. This setting allows you to choose between Axios, Fetch, or the Node HTTPS module, depending on your preference or requirements.

Valid values are:

Value	Description
axios	Use the Axios HTTP client
fetch	Use the Fetch HTTP client
https	Use the Node HTTPS module

If this value is not set, the fetch client is used.

bundle

Supported TypeScript SDK generation versions:

TypeScript v1	TypeScript v2
✅	✅

Setting the bundle option to true will configure the TypeScript SDK so that it can be bundled using tsup.

{
    ...
    "languageOptions": {
        "typescript": {
            "bundle": true
        }
    }
    ...
}

If this value is not set, it will default to false and not configure the SDK for bundling.

To bundle the SDK, once it has been created run the following commands from the output/typescript folder:

npm install
npm run build

This will bundle the SDK, creating the bundles in the dist folder. 2 bundles are created:

Bundle	Description
index.cjs	The SDK bundled as a CommonJS module
index.js	The SDK bundled as an ES Module

exportClassDefault

Supported TypeScript SDK generation versions:

TypeScript v1	TypeScript v2
✅	✅

The exportClassDefault setting determines whether or not the SDK exports the main class as default. If this is set to true, then the SDK will export the main class as default. For example, if you have an SDK called Exciting-Soda, you can import it using:

import ExcitingSoda from 'excitingsoda';

If this is set to false, then the SDK will export the main class as a named export, and you import it using:

import { ExcitingSoda } from 'excitingsoda';