SDK customization options

The customizations section is used to customize your SDKs.

Setting	Type	Required	Default	Description
`authentication`	`object`	❌	N/A	Customization the API authentication settings
`documentation`	`object`	❌	N/A	Customization the documentation generation settings
`generateEnv`	`bool`	❌	`true`	Should example .env files be generated?
`license`	`object`	❌	N/A	What license should the SDKs be covered under?
`retry`	`object`	❌	N/A	Retry functionality customization
`injectedModels`	`array`	❌	N/A	A list of models to inject into their parent models
`environmentVariables`	`array`	❌	N/A	A list of environment variables to inject into the SDKs
`refreshToken`	`object`	❌	N/A	Refresh token customization
`environments`	`array`	❌	N/A	A list of deployment environments
`inferServiceNames`	`bool`	❌	`false`	Should the SDKs infer service names from the spec?
`responseHeaders`	`bool`	❌	`false`	Should response headers be included in the response object.
`devContainer`	`bool`	❌	`false`	Should the generated SDKs contain the files to be able to run it as a dev container
`includeOptionalSnippetParameters`	`bool`	❌	`true`	Should optional parameters be included in the code snippets in generated documentation
`endpointCustomizations`	`object`	❌	N/A	Customize an endpoint based on a path and method name

`authentication`

Supported SDK languages and versions:

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

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

The authentication options allow you to configure the authentication that your API uses, that is set using the auth options. This section is an object with the following options:

Option	Type	Required	Default	Description
`access`	`object`	❌	N/A	Custom access token authentication options
`apiKey`	`object`	❌	N/A	API key authentication options

You can read more on authentication in our authentication guide.

`access`

The access options allow you to configure the custom access token that is sent to your API when the auth option is set to custom. This section is an object with the following options:

Option	Type	Required	Default	Description
`prefix`	`string`	❌	N/A	The prefix to use for the custom access token authentication

`prefix`

The prefix is used to define a custom prefix when using an access token. By default when using custom access token authentication, the Authorization header is passed as Bearer <token>. For example, if your bearer token is Passw0rd123!, the header would be:

Header	Value
`Authorization`	`Bearer Passw0rd123!`

By setting the prefix, you can replace Bearer with the value of your choice.

For example, if you have the following:

{
  ...
  "auth": [
    "custom"
  ],
  "customizations": {
    "authentication": {
      "access": {
        "prefix": "Token"
      }
    }
  }
  ...
}

Then the header would be:

Header	Value
`Authorization`	`Token Passw0rd123!`

`apiKey`

The apiKey option is used to configure the API key authentication for the SDKs. This is used if the auth setting is set to apikey. This is an object with the following options:

Option	Type	Required	Default	Description
`header`	`string`	❌	`X-API-KEY`	The header to use for the API key authentication

`header`

The header option sets the header to use for the API key authentication. This is used by the SDKs to set the header when making requests to the API. For example, if you have the following:

{
  ...
  "customizations": {
    "authentication": {
      "apiKey": {
        "header": "MY_CUSTOM_APIKEY_HEADER"
      }
    }
  }
  ...
}

Then the API key will be passed to your API using the MY_CUSTOM_APIKEY_HEADER header.

If this is not set, then API keys by default will be passed using the X-API-KEY header.

`documentation`

The documentation options allow you to configure the documentation that is generated with your SDK. You define what types of documentation is created using the the docs options. This section is an object with the following options:

Option	Type	Required	Default	Description
`snippets`	`object`	❌	N/A	SDK snippets customization options

You can read more about documentation generation in our documentation generation guide.

`snippets`

Supported SDK languages and versions:

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

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

The snippets options allow you to configure the code snippets that are generated in the documentation. This is an object with the following options:

Option	Type	Required	Default	Description
`format`	`string`	❌	`markdown`	The format of the code snippets

`format`

The format of the code snippets that are generated in the documentation.

Valid values are:

Value	Description
`markdown`	Generate snippets as markdown
`json`	Generate snippets as JSON

`generateEnv`

Supported SDK languages and versions:

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

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

If this option is set to true, then an example .env file is created in the SDK with the name .env.example to set environment variables for authentication. This can be used by your SDK users to configure their environment variables.

For example, if you have an API that uses a bearer token then this will need to be passed to the SDK on initialization, and it is good practice for this to be read from an environment variable or other configuration instead of being hard coded.

In TypeScript you would initialize the SDK using code like this:

import { ExcitingSoda } from 'excitingsoda';

const sdk = new ExcitingSoda({ accessToken: process.env.EXCITINGSODA_ACCESS_TOKEN });

The EXCITINGSODA_ACCESS_TOKEN environment variable will be defined in the .env.example:

EXCITINGSODA_ACCESS_TOKEN=

info

The naming convention of .env.example is standard practice as .env files are normally not committed to source code control, and are usually ignored in .gitignore files.

In Java you would initialize the SDK using code like this:

import soda.exciting.ExcitingSoda;

public class Main {

  public static void main(String[] args) {
    ExcitingSoda client = new ExcitingSoda(System.getenv("EXCITINGSODA_ACCESS_TOKEN"));
  }
}

The EXCITINGSODA_ACCESS_TOKEN environment variable will be defined in the .env.example:

EXCITINGSODA_ACCESS_TOKEN=

info

The naming convention of .env.example is standard practice as .env files are normally not committed to source code control, and are usually ignored in .gitignore files.

In Python you would initialize the SDK using code like this:

from os import getenv
from excitingsoda import ExcitingSoda

sdk = ExcitingSoda()
sdk.set_access_token(getenv("EXCITINGSODA_ACCESS_TOKEN"))

The EXCITINGSODA_ACCESS_TOKEN environment variable will be defined in the .env.example:

EXCITINGSODA_ACCESS_TOKEN=

info

The naming convention of .env.example is standard practice as .env files are normally not committed to source code control, and are usually ignored in .gitignore files.

In Go you would initialize the SDK using code like this:

import (
	"os"

	"github.com/exciting-soda/exciting-soda-go-sdk/pkg/excitingsoda"
	"github.com/exciting-soda/exciting-soda-go-sdk/pkg/excitingsodaconfig"
	"github.com/exciting-soda/exciting-soda-go-sdk/pkg/pets"
)

func main() {
	loadEnv()

	config := excitingsodaconfig.NewConfig()
    config.SetAccessToken(os.Getenv("ACCESS_TOKEN"))
	client := excitingsoda.NewExcitingSoda(config)
}

The default example code includes a helper function called loadEnv that reads the .env file and sets the environment variables. The ACCESS_TOKEN environment variable is used to set the access token in the config object.

The ACCESS_TOKEN environment variable will be defined in the .env.example:

ACCESS_TOKEN=

`license`

Supported SDK languages and versions:

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

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

The license option sets the open source license for the SDKs, if wanted. This is used in the LICENSE file that is created with the SDKs, as well as in the package manifests (such as the TypeScript package.json or Java pom.xml files). This is an object with the following options:

Option	Type	Required	Default	Description
`type`	`string`	❌	`NONE`	The type of license to use. If this is not set, the default is to not set a license
`url`	`string`	❌	`""`	The URL of a custom license if the `type` is set to `CUSTOM`

`type`

The type of license - such as one of a set of popular licenses, or a custom license.

Valid values are:

Value	Description
`MIT`	MIT
`GPL3`	GPL 3.0
`APACHE`	Apache 2.0
`NONE`	No license information will be set
`CUSTOM`	Use a custom license

For example, to use an MIT license for your SDK:

{
  ...
  "customizations": {
    "license": {
      "type": "MIT"
    }
  },
  ...
}

If you set this to CUSTOM, then you will need to set the url to the URL of the license file to use.

`url`

The URL to a custom license file. The liblab CLI will need to be able to access this file, so the remote URL will need to be public, for example a source-available Business Source License (BSL) license available publicly on your website or in a public GitHub repo.

This is only used if the type option is set to CUSTOM. For example, to point the SDK to a custom license file, use the following:

{
  ...
  "customizations": {
    "license": {
      "type": "CUSTOM",
      "url": "https://exciting.soda/sdk/license.txt"
    }
  },
  ...
}

You can find a list of OSI approved licenses on the Open Source Initiative licenses page.

`retry`

Supported SDK languages and versions:

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

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

The retry setting is used to configure the retry functionality for the SDKs. This is an object with the following options:

Option	Type	Required	Default	Description
`enabled`	`bool`	❌	`false`	Should retry functionality be enabled?
`maxAttempts`	`integer`	❌	`3`	The maximum number of attempts to retry
`retryDelay`	`integer`	❌	`150`	The delay between retries in milliseconds

If this setting is not set, the SDKs will not have retry functionality enabled.

`enabled`

The enabled option determines whether or not retry functionality is enabled. If this is set to true, then the SDK will retry requests that fail due to network errors or server errors. If this is set to false, then the SDK will not retry requests.

`maxAttempts`

The maxAttempts option sets the maximum number of attempts to retry a request. For example, if this is set to 3, then the SDK will retry a request up to 3 times before giving up.

`retryDelay`

The retryDelay option sets the delay between retries in milliseconds. For example, if this is set to 150, then the SDK will wait 150 milliseconds between retries.

More retry options

An extended set of retry options is available in some languages.

Supported SDK languages and versions:

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

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

For languages that support extended retry options, you can set the following options:

Option	Type	Required	Default	Description
`retryDelayJitter`	`number`	❌	`50`	The jitter to use in the retry delay
`backOffFactor`	`number`	❌	`2`	The backoff factor to use for exponential backoff
`maxDelay`	`number`	❌	`5000`	The maximum delay in milliseconds between retries
`httpCodesToRetry`	`array`	❌	`[408, 429, 500, 502, 503, 504]`	The HTTP codes to retry
`httpMethodsToRetry`	`array`	❌	`["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]`	The HTTP methods to retry

`retryDelayJitter`

The retryDelayJitter option sets the jitter to use in the retry delay. For example, if this is set to 50, then the SDK will vary the delay between retries by a random number between 0 and 50 milliseconds.

`backOffFactor`

The backOffFactor option sets the backoff factor to use for exponential backoff. For example, if this is set to 2, then the SDK will double the amount of time between retries on each retry.

`maxDelay`

The maxDelay option sets the maximum delay in milliseconds between retries. For example, if this is set to 5000, then the maximum delay between retries will capped at 5 seconds.

`httpCodesToRetry`

The httpCodesToRetry option delimits the response HTTP status codes on which the SDK should retry.

`httpMethodsToRetry`

The httpMethodsToRetry option delimits the HTTP methods on which the SDK should retry.

`injectedModels`

Supported SDK languages and versions:

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

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

When liblab generates an SDK, it creates models for the request and response objects, as well as the different schemas defined in the components section of the API spec. Some schemas are composed of other schemas, and these are by default created as separate models.

For example, if you have:

"Message": {
  "properties": {
    "message": {
      "type": "string",
      "title": "Message"
    },
    "body": {
      "$ref": "#/components/schemas/MessageBody"
    }
  },
  "type": "object",
},
"MessageBody": {
  "properties": {
      "details": {
        "type": "string",
        "title": "Details"
      }
    },
    "type": "object"
}

Then the SDK will create 2 models, Messageand MessageBody. If you don't want the separate MessageBody model created, you can add "MessageBody" to the injectedModels array, and the MessageBody model will be injected into the Message model:

{
  ...
  "customizations": {
    "injectedModels": [
      "MessageBody"
    ]
  },
  ...
}

You will get the following:

export interface Message {
  message: string;
  body: Body;
}
interface Body {
  details: string;
}

public class Message extends soda.exciting.models.BaseModel {
  public static class Body extends soda.exciting.models.BaseModel {
    private final java.lang.String details;
  }

  private final Message.Body body;
  private final java.lang.String message;
}

class Body(BaseModel):
    def __init__(self, details: str, **kwargs):
        self.details = details


class Message(BaseModel):
    def __init__(self, body: Body, message: str, **kwargs):
        self.body = body
        self.message = message

`environmentVariables`

Supported SDK languages and versions:

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

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

The environmentVariables setting allows you to define environment variables that need to be set by the SDK user for the SDK to work - for example if you need values set that are used in code you create in a hook.

This setting 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 environment variable
`description`	`string`	✅	N/A	The value of the environment variable

These environment variables will be declared in the .env.example files that are created with each SDK (assuming this is enabled with the generateEnv setting). They will also be documented in the README for the SDK.

For example, if you have the following:

{
  ...
  "environmentVariables" : [
    {
      "name": "TEAM_NAME",
      "description": "The team name for the SDK user"
    }
  ],
  ...
}

This will add the following to the .env.example file:

TEAM_NAME=

And the following to the README:

## Environment Variables

You will need the following environment variables in order to access all the features of this SDK:

| Name      | Description                    |
| :-------- | :----------------------------- |
| TEAM_NAME | The team name for the SDK user |

`name`

The name for the environment variable.

`description`

The description for the environment variable. This is used for the README file only.

`refreshToken`

Supported SDK languages and versions:

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

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

The refreshToken setting is used to configure the refresh token functionality for the SDKs, to allow the SDK user to remain authenticated after their authentication expires. This is an object with the following options:

Option	Type	Required	Default	Description
`endpoint`	`string`	✅	N/A	The endpoint to use for refreshing the token
`bearerKey`	`string`	✅	N/A	The response property to use to get the bearer token from the response
`refreshKey`	`string`	✅	N/A	The response property to use to get the refresh token from the response

If your API supports refresh tokens for authentication, then this needs to be set. If this section is not set, then the SDKs will not have refresh token functionality enabled. You can read more about refresh tokens in our authentication guide.

These values need to match your spec - the endpoint needs to be defined as a supported path that can receive POST requests, and the bearerKey and refreshKey must be valid fields in the response from the endpoint.

`endpoint`

This is the endpoint to use to refresh the token.

`bearerKey`

The bearerKey is the name of the key in the response from the refresh token endpoint that contains the access token that the SDK can use to continue authenticating with the API.

For example, if this is the response from the endpoint that is defined in your API spec:

"RefreshTokenPair": {
  "properties": {
      "accessToken": {
          "type": "string"
      },
      "refreshToken": {
          "type": "string"
      }
  },
  "required": [
      "accessToken",
      "refreshToken"
  ],
  "type": "object"
},

Then the bearerKey should be set to accessToken:

{
  "customizations": {
    "refreshToken": {
      ...
      "bearerKey": "accessToken"
    }
  }
}

`refreshKey`

The refreshKey is the name of the key in the response from the refresh token endpoint that contains the refresh token that the SDK can use to continue refreshing the access token with the API.

For example, if this is the response from the endpoint that is defined in your API spec:

"RefreshTokenPair": {
  "properties": {
      "accessToken": {
          "type": "string"
      },
      "refreshToken": {
          "type": "string"
      }
  },
  "required": [
      "accessToken",
      "refreshToken"
  ],
  "type": "object"
},

Then the refreshKey should be set to refreshToken:

{
  "customizations": {
    "refreshToken": {
      ...
      "refreshKey": "refreshToken"
    }
  }
}

`environments`

Supported SDK languages and versions:

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

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

Your API may have multiple environments or locations, such as preview and production, or NorthAmerica, EMEA, and APAC. This setting allows you to configure environments to be added to the SDKs as constant values that are passed in when creating the SDK client.

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 environment
`url`	`string`	✅	N/A	The URL for the environment

You can read more about configuring URLs and setting these at run time in our URLs and environments guide.

`name`

The name option sets the name of the environment. This is used as the name of the constant in the SDK, and is used when creating the SDK client. This name must not have any invalid characters that would not be allowed in constant names. For example, DevNA is valid, Dev NA is not.

`url`

The url option sets the URL for the environment. This is used as the value of the constant in the SDK, and is used when creating the SDK client. This is validated to ensure it is a valid URL.

`inferServiceNames`

Supported SDK languages and versions:

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

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

The inferServiceNames flag determines if service names for the SDK should be inferred from the endpoint names rather than tags if they all share a common prefix.

The OpenAPI specification has tags that are used to group service endpoints. For example:

tags:
- name: Boba
  description: Operations for boba
- name: Soda
  description: Operations for soda
paths:
 "/boba":
    get:
      tags:
      - Boba
  ...
 "/boba/{id}":
    post:
      tags:
      - Boba
  ...
 "/soda":
    get:
      tags:
      - Soda
  ...

In this case, the Boba tag is used to group the GET and POST operations for the /boba endpoints, and the Soda tag is used for the /soda endpoint. Using tags means the services in your SDK will be created based on these tags - for example in this case you would have a BobaService with methods to get and post boba, and a SodaService with a method to get soda.

tags are optional, so you many not have these defined in your spec. You may also have a common prefix to your endpoint, such as a version number:

paths:
 "/v2/boba":
    get:
  ...
 "/v2/boba/{id}":
    post:
  ...
 "/v2/soda":
    get:
  ...

In this case the liblab CLI would default to creating a V2Service service with methods to get and post boba, and get soda. This may not be what you want, you may want to have a BobaService and SodaService service instead.

To avoid this set the inferServiceNames option to true to infer the service names from the endpoint paths.

{
  ...
  "customizations": {
    "inferServiceNames": true
  },
  ...
}

In this case, this would look at all the endpoints, and if they have a common prefix, then this would be ignored for the service names. Instead of a V2Service service, you would get a BobaService and SodaService.

This only works if your endpoints all have the same common prefix. For example, if you have some endpoints that are v2 and some that are v3 then service names cannot be inferred, as this may lead to name clashes (for example both services having a GET endpoint for boba). In this case, it is recommended to use tags in your OpenAPI spec.

`responseHeaders`

Supported SDK languages and versions:

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

note
Response headers are currently always included in the Go SDKs.

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

When responses come back from API calls, they can contain data, as well as important information in the headers. By default, the SDKs will only return the data from the response, and ignore the headers. If you want to include the headers in the response, then set this option to true.

For example, if you have a response object like this:

paths:
  /soda/{id}:
    get:
      operationId: getSoda
      parameters:
        - name: id
          in: path
          required: true
          description: The id of the soda
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Soda'
components:
  schemas:
    Soda:
      type: object
      properties:
        name:
          type: string
        id:
          type: string

If the response headers option is not set, or set to false, then the generated getSoda method will look like this:

async getSoda(id: string): Promise<Soda> {
    ...
}

public soda.exciting.models.Soda getSoda(String id) throws ApiException {
    ...
}

public Soda getSoda(@NonNull String id) throws ApiException {
    ...
}

def get_soda(self, id: str) -> SodaModel:
    ...

def get_soda(self, id: str) -> SodaModel:
    ...

public async Task<Soda> GetSodaAsync(string id)

Setting this option to false is not supported. Go SDKs currently always return headers with the response.

If you set the response headers option to true:

{
  ...
  "customizations": {
    "responseHeaders": true
  },
  ...
}

The the return values from calls to the SDK services will be a wrapper object containing the response data, as well as a dictionary of the headers. The getSoda method will look like this:

async getSoda(id: string): Promise<Response<Soda>> {

With the Response<T> type looking like this:

export default interface Response<T> {
  data: T;
  headers: Record<string, string>;
}

If this call returned a header such as Content-Range, this would be in the headers dictionary.

The the return values from calls to the SDK services will be a wrapper object containing the response data, as well as a dictionary of the headers. The getSoda method will look like this:

public ResponseWithHeaders<soda.exciting.models.Soda> getSoda(String id) throws ApiException

With the ResponseWithHeaders<T> class looking like this:

public class ResponseWithHeaders<T> {

  private T data;
  private Headers headers;

  public ResponseWithHeaders(T data, Headers headers) {
    this.data = data;
    this.headers = headers;
  }

  public T getData() {
    return data;
  }

  public Headers getHeaders() {
    return headers;
  }
}

If this call returned a header such as Content-Range, this would be in the Headers dictionary.

The the return values from calls to the SDK services will be a wrapper object containing the response data, as well as a dictionary of the headers. The get_soda method will look like this:

def get_soda(self, id: str) -> ResponseWithHeaders:

With the ResponseWithHeaders type looking like this:

class ResponseWithHeaders:
    def __init__(self, data, headers):
        self.data = data
        self.headers = headers

If this call returned a header such as Content-Range, this would be in the headers dictionary.

All response objects returned by Go SDKs include metadata that includes response Headers, and the HTTP status code returned from the request. For example, the GetSoda method will look like this:

func (api *SodaService) GetSoda(ctx context.Context, id string) 
    (*shared.ExcitingSodaResponse[Soda], *shared.ExcitingSodaError) {
}

With the shared.ExcitingSodaResponse[Soda] object including the response headers and status code as metadata:

type ExcitingSodaResponse[T any] struct {
    Data     T
    Metadata ExcitingSodaResponseMetadata
}

type ExcitingSodaResponseMetadata struct {
    Headers    map[string]string
    StatusCode int
}

`devContainer`

Supported SDK languages and versions:

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

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

The devContainer option determines if the generated SDKs should include the files to be able to open and run the SDK using a dev container.

A dev container is a development environment setup that is containerized using technologies like Docker, making it consistent and reproducible across different development machines. It contains everything needed for the development environment, including the programming language, dependencies, libraries, tools and extensions.

If you set this to true, every SDK generated will include a devcontainer.json file, allowing you to start using the SDK as soon as it's produced from inside any IDE that supports development containers, such as VS Code. Additionally, each SDK will have a VS Code launch.json file so you can run and debug the SDK example.

{
  ...
  "customizations": {
    "devContainer": true
  },
  ...
}

You can read more on development containers in the development containers documentation.

`includeOptionalSnippetParameters`

Supported SDK languages and versions:

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

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

The includeOptionalSnippetParameters option determines if optional and deprecated parameters should be included in the code snippets in generated documentation or not.

If this is set to true (the default), then optional parameters will be included in the code snippets in the generated documentation. If this is set to false, then optional parameters will not be included in the code snippets in the generated documentation.

For example, if you have an endpoint with an optional parameter:

paths:
  /llamas:
    get:
      operationId: getAllLlamas
      description: Retrieve a list of all llamas
      parameters:
        - name: age
          in: query
          description: Age of the llamas to get
          example: 5
          required: false
          schema:
            type: integer

With this option set to true, the code snippets in the generated documentation will include the optional parameter:

const result = await sdk.llamas.getAllLlamas({ age: 5 });

const result = await sdk.llamas.getAllLlamas();

GetAllLlamasParameters requestParameters = GetAllLlamasParameters.builder()
  .age(5L)
  .build();

List<Llama> response = sdk.llamas.getAllLlamas(requestParameters);

sdk = ExcitingSoda()
results = sdk.llamas.get_all_llamas(age = 5)

sdk = ExcitingSoda()
result = sdk.llamas.get_all_llamas(age=5)

$sdk = new Client();
$response = $sdk->Llamas->getAllLlamas(age: 123);

If this option is set to false, the code snippets in the generated documentation will not include the optional parameter:

const result = await sdk.llamas.getAllLlamas();

const result = await sdk.llamas.getAllLlamas();

List<Llama> response = sdk.llamas.getAllLlamas();

sdk = ExcitingSoda()
results = sdk.llamas.get_all_llamas()

sdk = ExcitingSoda()
result = sdk.llamas.get_all_llamas()

$sdk = new Client();
$response = $sdk->Llamas->getAllLlamas();

`endpointCustomizations`

Supported SDK languages and versions:

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

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

The endpointCustomizations setting is used to customize various HTTP methods on API endpoints. This is an object with the following structure:

{
  ...
  "customizations": {
    "endpointCustomizations": {
      "/pets": {
        "get":  { ... }
      }
    }
  }
  ...
}

Supported HTTP methods:

get post put delete patch
✅ ✅ ✅ ✅ ✅

get	post	put	delete	patch
✅	✅	✅	✅	✅

Each endpoint path and HTTP method combo that appears in your OpenAPI spec has the following customization options:

Option	Type	Required	Default	Description
`operationId`	`string`	❌	N/A	A new operationId name

`operationId`

This customization allows you to override an existing or missing operationId for a specific endpoint path and HTTP method combination. For example, if your OpenAPI specification contains the following endpoint and you want to change its operationId:

{
  ...
   "paths": {
      "/pets": {
         "get": {
            "operationId": "123aBadOperationId",
          }
          ...
      }
      ...
   }
  ...
}

You can override the existing operationId without directly altering your OpenAPI spec by using the operationId customization with a new name:

{
  ...
  "customizations": {
    "endpointCustomizations": {
      "/pets": {
        "get":  {
           "operationId": "getPets"
        }
      }
    }
  }
  ...
}

Now the final SDK will be generated with the customized operationId:

TypeScript Example Before Customization
TypeScript Example After Customization

async 123aBadOperationId(params?: 123aBadOperationIdParams, requestConfig?: RequestConfig): Promise<HttpResponse<Pet[]>> {
    ...
}

async getPets(params?: getPetsParams, requestConfig?: RequestConfig): Promise<HttpResponse<Pet[]>> {
    ...
}

`streaming`

This customization allows you to add streaming support for a specific endpoint path and HTTP method combination.

Adding streaming support means that the SDK will return one or more responses for a single HTTP call. This is useful when you have an endpoint that returns a stream of data, such as the tokens resulting from a call to a Large Language Model (AI model).

Notes:

Currently this feature is only supported in Python v2.
Streaming support is automatically added for endpoints that return a text/event-stream content type.

For example, if your OpenAPI specification contains the following endpoint and you want to add streaming support to it:

{
  ...
   "paths": {
      "/generate": {
         "post": {
            "operationId": "generate",
            "requestBody": {
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/GenerateRequest"
                  }
                }
              }
            },
            "responses": {
              "200": {
                "description": "Successful response",
                "content": {
                  "application/json": {
                    "schema": {
                      "$ref": "#/components/schemas/GenerateResponse"
                    }
                  }
                }
              }
            }
          }
          ...
      }
      ...
   }
  ...
}

You can add streaming support without altering your OpenAPI spec by using the streaming customization:

{
  ...
  "customizations": {
    "endpointCustomizations": {
      "/generate": {
        "post":  {
           "streaming": "true"
        }
      }
    }
  }
  ...
}

`pagination`

Pagination simplifies handling large datasets by automatically managing paginated API responses. This feature allows developers to retrieve and iterate through data page-by-page efficiently, eliminating the need for manual effort. Developers can focus on core functionality while the SDK seamlessly handles API pagination.

liblab enables pagination customization in two ways:

Directly through your OpenAPI spec using the x-liblab-pagination annotation.
Via your liblab.config.json file through endpoint customization.

Supported SDK languages and versions:

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

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

'x-liblab-pagination' annotation

You can define endpoint pagination directly on your OpenAPI Spec using the x-liblab-pagination annotation like this:

"paths": {
  "/pets": {
    "get": {
      "operationId": "listPets",
      "x-liblab-pagination": {
        "paginationType": "offsetLimit",
        "inputFields": [
          { "name": "offset", "in": "query", "type": "offset" },
          { "name": "limit", "in": "query", "type": "limit" }
        ],
        "resultsArray": {
          "results": "$.pets"
        }
      }
    }
  }
}

These are the fields which will be used to generate the output code:

Field	Description
`paginationType`	Specifies the pagination method used. In this case, `"offsetLimit"` indicates the use of offset and limit pagination.
`inputFields`	An array of objects defining the pagination parameters sent in the API request.
`inputFields.name`	The name of the parameter as specified in your API.
`inputFields.in`	Specifies where the parameter is located, such as `"query"` (in the URL query string).
`inputFields.type`	Defines the purpose of the field, such as `"offset"` (starting point of data) or `"limit"` (maximum number of items).
`resultsArray`	Defines where the paginated results are located within the API response.
`resultsArray.results`	A JSON path (e.g., `$.pets`) pointing to the array in the response that contains the paginated data within the response.

`liblab config endpoint customizations`

You can also add this same information to the liblab config file. This is useful when your spec file is machine generated, and you want to store this data somewhere other than the spec file itself.

The schema in the liblab config file is very similar to the x-liblab-pagination annotation.

{
  "customization": {
    "endpointCustomizations": {
      "/pets": {
        "get": {
          "pagination": {
            "paginationType": "limitOffset",
            "inputFields": [
              {
                "name": "limit",
                "in": "query",
                "type": "limit"
              },
              {
                "name": "offset",
                "in": "query",
                "type": "offset"
              }
            ],
            "resultsArray": {
              "results": "$.page",
              "defaultPageSize": 5
            }
          }
        }
      }
    }
  }
}

`Paginated Endpoints`

Iterable Pagination

Paginated endpoints are designed to handle large sets of data by breaking them into smaller, manageable chunks called "pages." This approach improves performance and user experience by loading data incrementally rather than all at once. There are two common types of pagination methods: iterable pagination and manual pagination.

A paginated endpoint returns a special kind of response that is iterable so you can use it in a for loop. Note that each page is a response object with the usual metadata for debugging, and the page array itself is located inside the data property

TypeScript v2

const pages = await sdk.pets.listPets({ limit: 3, offset: 0 });

for await (let page of pages) {
  console.log(page.data);
}

Manual Pagination

SDK users can also paginate through a list like this one-by-one using the next function on the paginated response interface.

TypeScript v2

const pages = await sdk.pets.listPets({ limit: 3, offset: 0 });

const firstPage = pages.next();
console.log(firstPage.value.data);

const secondPage = pages.next();
console.log(secondPage.value.data);

authentication​

access​

prefix​

apiKey​

header​

documentation​

snippets​

format​

generateEnv​

license​

type​

url​

retry​

enabled​

maxAttempts​

retryDelay​

More retry options​

retryDelayJitter​

backOffFactor​

maxDelay​

httpCodesToRetry​

httpMethodsToRetry​

injectedModels​

environmentVariables​

name​

description​

refreshToken​

endpoint​

bearerKey​

refreshKey​

environments​

name​

url​

inferServiceNames​

responseHeaders​

devContainer​

includeOptionalSnippetParameters​

endpointCustomizations​

operationId​

streaming​

Notes:​

pagination​

'x-liblab-pagination' annotation​

liblab config endpoint customizations​

Paginated Endpoints​

Iterable Pagination​

Manual Pagination​

`authentication`

`access`

`prefix`

`apiKey`

`header`

`documentation`

`snippets`

`format`

`generateEnv`

`license`

`type`

`url`

`retry`

`enabled`

`maxAttempts`

`retryDelay`

More retry options

`retryDelayJitter`

`backOffFactor`

`maxDelay`

`httpCodesToRetry`

`httpMethodsToRetry`

`injectedModels`

`environmentVariables`

`name`

`description`

`refreshToken`

`endpoint`

`bearerKey`

`refreshKey`

`environments`

`name`

`url`

`inferServiceNames`

`responseHeaders`

`devContainer`

`includeOptionalSnippetParameters`

`endpointCustomizations`

`operationId`

`streaming`

Notes:

`pagination`

'x-liblab-pagination' annotation

`liblab config endpoint customizations`

`Paginated Endpoints`

Iterable Pagination

Manual Pagination