Core SDK options

The core SDK options configure the basic settings, such as the location of the spec to use, the SDK languages to generate, and the authentication type to use. These options are set at the top level of the liblab config file.

Option	Type	Required	Default	Description
sdkName	string	❌ 1	N/A	The name of the SDK
apiName	string	❌ 2	N/A	The name of the API. If this is not set, this value is populated from the API spec.
apiVersion	string	❌ 3	N/A	The version of the API. If this is not set, this value is populated from the API spec.
baseUrl	string	❌	""	The base URL of the API
specFilePath	string	✅	N/A	The path to the API spec, either a local path or a URL
languages	array	❌	[ "csharp", "go", "python", "typescript" ]	The list of languages to generate SDKs for
auth	array	❌	None	The type of authentication to use
createDocs (deprecated)	bool	❌	false	Should developer documentation be generated? This option is deprecated, and should be replaced by using the docs option.
docs	array	❌	N/A	The type of documentation to generate for your SDK, such as API docs, or SDK snippets.
customizations	object	❌	N/A	Customizations to SDKs. See the SDK customization options documentation for more details
languageOptions	object	❌	N/A	Language specific options for the SDKs. See the SDK language options documentation for more details
publishing	object	❌	N/A	Publishing options for the SDKs. See the SDK publishing options documentation for more details
validationsToIgnore	array	❌	N/A	A list of API spec validations to ignore. See the API spec validations options documentation for more details
workflows	object	❌	N/A	The workflows definition
integrations	object	❌	N/A	Integration options for LibLab, which allow you to connect to external services or platforms such as API documentation providers. Each integration can be configured to interact with LibLab SDKs and API workflows for streamlined operations.

¹ sdkName is required if your spec file doesn't have the title or name set, depending on the spec type. See the sdkName section for more information.

² apiName is required if your spec file doesn't have the title or name set, depending on the spec type. See the apiName section for more information.

³ apiVersion is required if your spec file doesn't have the version set. See the apiVersion section for more information.

sdkName

Supported SDK languages and versions:

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

The sdkName is used to set the name for your SDK. This name is used for the package name for the different SDKs, it is used to name the class that provides SDK access, and is used in the README and other documentation.

This name will be re-cased to be idiomatic for the SDK language. For example - if you set the sdkName to Exciting-Soda:

liblab.config.json

{
    "sdkName": "Exciting-Soda"
    ...
}

You will get the following:

TypeScript v1

The SDK will be in TypeScript package called excitingsoda.

package.json

{
  "name": "excitingsoda",
}

The class you would use to access the SDK would be called ExcitingSoda:

src/index.ts

import { ExcitingSoda } from 'excitingsoda';

const sdk = new ExcitingSoda();

TypeScript v2

The SDK will be in TypeScript package called exciting-soda.

package.json

{
  "name": "exciting-soda",
}

The class you would use to access the SDK would be called ExcitingSoda:

src/index.ts

import { ExcitingSoda } from 'exciting-soda';

const sdk = new ExcitingSoda();

Java v1

The SDK will be in Maven package with a artifact Id of ExcitingSoda.

pom.xml

<?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">
    <modelVersion>4.0.0</modelVersion>
    
    <artifactId>
        exciting-soda
    </artifactId>
</project>

The class you would use to access the SDK would be called ExcitingSoda:

import soda.exciting.ExcitingSoda;

public class Main {

  public static void main(String[] args) {
    ExcitingSoda client = new ExcitingSoda();
  }
}

Java v2

The SDK will be in a Maven package with the artifact Id of ExcitingSoda.

pom.xml

<?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">
    <modelVersion>4.0.0</modelVersion>
    
    <artifactId>
        exciting-soda
    </artifactId>
</project>

note

This can be overridden by the artifactId option in the language options section of your config file.

The class you would use to access the SDK would be called ExcitingSoda:

import soda.exciting.ExcitingSoda;

public class Main {

  public static void main(String[] args) {
    ExcitingSoda client = new ExcitingSoda();
  }
}

Python v1

The SDK will be in Python package called excitingsoda.

pyproject.toml

[project]
name = "excitingsoda"

The class you would use to access the SDK would be called ExcitingSoda:

app.py

from excitingsoda import ExcitingSoda

sdk = ExcitingSoda()

Python v2

The SDK will be in Python package called exciting_soda.

pyproject.toml

[project]
name = "exciting_soda"

The class you would use to access the SDK would be called ExcitingSoda:

app.py

from exciting_soda import ExcitingSoda

sdk = ExcitingSoda()

C#

The SDK will be in a project called ExcitingSoda in a project file called ExcitingSoda.csproj.

ExcitingSoda.csproj

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <RootNamespace>ExcitingSoda</RootNamespace>
    <PackageId>ExcitingSoda</PackageId>
  </PropertyGroup>
</Project>

The class you would use to access the SDK would be called ExcitingSodaClient in the ExcitingSoda namespace:

Program.cs

using ExcitingSoda;

var client = new ExcitingSodaClient();

Go

The SDK will be in a package called excitingsoda.

excitingsoda.go

package excitingsoda

type ExcitingSoda struct {
}

func NewExcitingSoda(config excitingsodaconfig.Config) *ExcitingSoda {
}

The SDK client struct you would use to access the SDK would be called ExcitingSoda which can be created with the NewExcitingSoda function:

main.go

package main

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

func main() {
    config := excitingsodaconfig.NewConfig()
    excitingSoda := excitingsoda.NewExcitingSoda(config)
}

PHP

The class you would use to access the SDK would be called Client in the ExcitingSoda namespace:

index.php

<?php

use ExcitingSoda\Client;

$client = new Client();

?>

If the sdkName is not set, the SDK name is taken from the title field in your API spec.

openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "ExcitingSoda",
    ...
  }
  ...
}

If the title is also not set, the liblab build command will raise an error.

apiName

Supported SDK languages and versions:

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

The name of the API. This is used to identify the API in the liblab portal. If the apiName is not set, the API name is taken from the name in the API spec.

For Swagger and OpenAPI specs, this is the title field in the info object.

spec.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "ExcitingSoda",
    ...
  }
  ...
}

For Postman Collections this is the name field in the info object.

postman-collection.json

{
  "info": {
    "name": "ExcitingSoda",
    ...
  }
  ...
}

The API name is a required field for Swagger, OpenAPI and Postman Collections, so if this is not set in either the config file or the spec, an error will be raised.

apiVersion

Supported SDK languages and versions:

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

The version of the API. This is used to identify the API in the liblab web portal. If the apiVersion is not set, the API version is taken from the version in the API spec.

For Swagger and OpenAPI specs, this is the version field in the info object.

spec.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "ExcitingSoda",
    "version": "1.0.1"
    ...
  }
  ...
}

For Postman Collections this is the version field in the info object.

postman-collection.json

{
  "info": {
    "name": "ExcitingSoda",
    "version": "1.0.1"
    ...
  }
  ...
}

The API name is a required field for Swagger and OpenAPI, but is not a required field for Postman Collections. Although this field is not required in the liblab config file, If this is not set in either the config file or the spec, an error will be raised as a value for the version is required to generate an SDK.

baseUrl

Supported SDK languages and versions:

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

The baseUrl is the URL for your API. If this is not set, the SDK defaults to using first value that is found in the servers object of your API spec.

Java SDK group Id

For Java SDKs, the baseUrl is also used as the group Id, unless you set the groupId language customization option. For example if you have:

liblab.config.json

{
    ...
    "baseUrl": "https://exciting.soda"
    ...
}

Then your Java group Id will be soda.exciting:

pom.xml

<?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">
    <modelVersion>4.0.0</modelVersion>
    <groupId>soda.exciting</groupId>
    ...
</project>

This can be accessed from the soda.exciting package:

main/java/soda/exciting/ExcitingSoda.java

package soda.exciting;

public class ExcitingSoda {
}

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

specFilePath

Supported SDK languages and versions:

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

The specFilePath is the path or URL of your spec file. This can be a local file, or a remote URL. For remote URLs, the liblab CLI will need to be able to access this file, so it will need to be public.

The spec file can be in JSON or YAML format. See our supported API specifications document for more information on the supported spec formats.

languages

Supported SDK languages and versions:

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

The languages setting is an array of the languages you want to generate SDKs for. You can find a list of the supported languages in our SDK language support document.

liblab.config.json

{
  ...
  "languages": [
    "java",
    "python",
    "typescript",
    "csharp",
    "go",
    "terraform"
  ]
  ...
}

Language specific customizations can be set in the languageOptions section of the config file.

auth

Supported SDK languages and versions:

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

The auth setting defines the authentication your API uses. This setting is optional. If not set, the SDKs will not include any authentication.

liblab.config.json

{
  ...
  "auth":  [
    "apikey"
  ]
  ...
}

Valid values are:

Value	Description
apikey	API key authentication, passing an API key as a header to all API calls.
basic	Basic authentication, passing a username and password in the Authentication header to all API calls.
bearer	Bearer token authentication, passing a bearer token in the Authentication header to all API calls, with the value prefixed with bearer.
custom	Custom access token authentication, passing an access token in the Authentication header to all API calls, with the value prefixed with a custom prefix.
oauth	OAuth authentication allows secure token-based access to resources on behalf of a user. The client obtains an access token through an OAuth flow and then includes this token in the Authentication header of API requests.

If your API supports multiple authentication types, you can have multiple values as long as they don't conflict. For example, both Basic authentication and Bearer token authentication use the Authentication header in your API, so you can't have both set simultaneously.

The auth options can be customized using the authentication section of the customizations options. You can, for example, set the API key header or the access token prefix.

You can access the Authentication guide to read more about the authentication options available and their configuration.

createDocs

Deprecated

This option has been deprecated in favor of the docs option, and will be removed in a future release. The docs option gives you more control, and allows you to create documentation in different ways. Please upgrade your config file to use the new option.

Supported SDK languages and versions:

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

The createDocs setting is a boolean that determines whether or not to generate documentation for your SDKs. Set this true to automatically generate docs, or false (the default) to skip this step.

liblab.config.json

{
  ...
  "createDocs": true
  ...
}

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

docs

Supported SDK languages and versions:

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

note

See our documentation generation guide for more details on SDK language support for the different documentation options.

The docs setting defines the type of documentation to generate for your SDKs. This setting is optional, and if not set, the SDKs will not include any documentation.

liblab.config.json

{
  ...
  "docs":  [
    "api",
    "snippets",
    "enhancedApiSpec"
  ]
  ...
}

Valid values are:

Value	Description
api	Generate a complete API documentation HTML site, with details on the API, and examples for using the generated SDKs. This is the equivalent to the deprecated createDocs setting.
snippets	Generate SDK snippets for all the endpoints, either as markdown or JSON. These snippets can then be imported into your existing documentation.
enhancedApiSpec	Generates an enhanced OpenAPI specification with liblab SDK code snippets. Each operation is enriched with an x-codeSamples array containing the relevant SDK samples.

You can have multiple values if you want to generate multiple types of documentation. These docs options can be further customized using the documentation section of the customizations options.

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

workflows

Supported SDK languages and versions:

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

workflows allow you to significantly reduce the complexity of your APIs for end users by combining multiple API steps into a simplified one-step workflow within the SDK.

To generate an SDK that incorporates workflows, first you must create an Arazzo specification that can be used as an input in the liblab config.

The Arazzo Specification is a component of the OpenAPI Initiative and offers a framework for detailing API call sequences. For guidance on crafting an Arazzo specification, refer to the Version 1.0.0 specification page.

Option	Type	Required	Default	Description
path	string	✅	N/A	A local relative path to your Arazzo specification file or a publicly reachable URL to the Arazzo spec file
outputName	string	❌	"workflows"	The desired output name for the workflow

For detailed instructions, refer to the new tutorial: Combine API Calls Using SDK Workflows

path

Specify the path to the Arazzo specification file, which outlines the workflow, in the liblab config. This Arazzo specification file can be in either JSON or YAML format. The path can be to a local file on your system or a file accessible via a publicly reachable URL.

liblab.config.json

{
  ...
  "workflows": {
    "path": "./path-to-your-spec"
  },
  ...
}

outputName

outputName is an optional parameter that allows you to create a custom name for the workflow folder, file, and class names.

liblab.config.json

{
  ...
  "workflows": {
    "path": "./path-to-your-spec",
    "outputName": "your-custom-output-name"
  },
  ...
}

Note that the outputName will be adjusted to adhere to the naming conventions specific to each programming language.