SDK language options

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

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
`githubRepoName`	`string`	❌	N/A	The name of the GitHub repository for the SDK
`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

`githubRepoName`

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.

`ignoreFiles`

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 have an API endpoint that you don't want exposed in your SDK.

For example, if you have an API with the endpoint /secret, you could hide this with the following:

TypeScript
Python
Java

In TypeScript hide the Secret.ts file that is generated in the services/secret folder.

{
    ...
    "languageOptions": {
        "typescript": {
            "ignoreFiles": [
                "/src/services/secret/Secret.ts"
            ]
        }
    }
    ...
}

In Python hide the secret.py file that is generated in the excitingsoda/services folder.

{
    ...
    "languageOptions": {
        "typescript": {
            "ignoreFiles": [
                "/src/excitingsoda/services/secret.py"
            ]
        }
    }
    ...
}

In Java hide the SecretService.java file that is generated in the services folder.

{
    ...
    "languageOptions": {
        "typescript": {
            "ignoreFiles": [
                "/src/main/java/soda/exciting/services/SecretService.java"
            ]
        }
    }
    ...
}

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

note

As well as ignoring services, make sure to ignore any models that those services use.

`sdkVersion`

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`

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`

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.

This is not supported for Java SDKs, and only one author is supported for TypeScript. If you set multiple authors for TypeScript, only the first one is used.

TypeScript
Python
Java

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

{
    ...
    "languageOptions": {
        "typescript": {
            "authors": [
                {
                    "name": "Llama Soda",
                    "email": "llama.soda@exciting.soda"
                }
            ]
        }
    }
    ...
}

will give a package.json file with:

{
    ...
    "author": "Llama Soda <llama.soda@exciting.soda>",
    ...
}

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

{
    ...
    "languageOptions": {
        "python": {
            "authors": [
                {
                    "name": "Llama Soda",
                    "email": "llama.soda@exciting.soda"
                },
                {
                    "name": "Llama Boba",
                    "email": "llama.boba@exciting.soda"
                }
            ]
        }
    }
    ...
}

will give a pyproject.toml file with:

[project]
authors = [
  { name="Llama Soda", email="llama.soda@exciting.soda" },
  { name="Llama Boba", email="llama.boba@exciting.soda" }
]
...

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`

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

TypeScript
Python
Java

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",
    ...
}

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"

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

`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 baseURL if this is set, or to the first entry in the servers list in the spec 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 baseURL or servers list. This will reduce the chance of your customers having clashes with split packages.

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`	If requests are sent as dictionaries instead of models, should they be validated for all mandatory fields

`pypiPackageName`

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`

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 BookRequest(BaseModel):
  def __init__(
    self,
    id: int,
    name: str = None,
    author: str = None,
    **kwargs,
  ):
    self.id = id

    self.name = name
    self.author = author

If this is set to False, you would get:

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

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

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

`classifiers`

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`

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`

The strictVersion setting sets whether or not to enforce strict dependency versions in the generated requirements.txt and pyproject.toml 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:

requirements.txt
pyproject.toml

requests
http-exceptions
pytest
responses

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

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

requirements.txt
pyproject.toml

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

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

`enforceRequestValidation`

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.

Setting enforceRequestValidation to True will validate in the SDK, setting it to False (the default) 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.

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`	❌	`axios`	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`

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`

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`

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 axios client is used.

`bundle`

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`

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';

Generic Language options​

githubRepoName​

ignoreFiles​

sdkVersion​

hookDependencies​

name​

version​

groupId​

authors​

name​

email​

homepage​

Java specific options​

groupId​

Python specific options​

pypiPackageName​

alwaysInitializeOptionals​

classifiers​

projectUrls​

strictVersion​

enforceRequestValidation​

TypeScript specific options​

npmOrg​

npmName​

httpClient​

bundle​

exportClassDefault​

Generic Language options

`githubRepoName`

`ignoreFiles`

`sdkVersion`

`hookDependencies`

`name`

`version`

`groupId`

`authors`

`name`

`email`

`homepage`

Java specific options

`groupId`

Python specific options

`pypiPackageName`

`alwaysInitializeOptionals`

`classifiers`

`projectUrls`

`strictVersion`

`enforceRequestValidation`

TypeScript specific options

`npmOrg`

`npmName`

`httpClient`

`bundle`

`exportClassDefault`