Quickstart - Generate an SDK from your OpenAPI spec

This quickstart walks you through generating an SDK from your OpenAPI spec using liblab.

note

Before working though this quickstart, make sure you have registered an account with liblab, installed liblab CLI and logged in. Check out the Getting Started guide for more information.

To generate an SDK, follow these steps:

1. Create a liblab configuration file
2. Generate your SDK
3. Review and test your SDK

Create a liblab configuration file

The liblab.config.json file is used to configure how SDKs are generated. It includes information such as the name of the SDK, the programming language, the API spec file to use, how your API authenticates, and more. By using a configuration file you don't need to decorate your API spec with liblab specific annotations.

To create a configuration file, run the following command:

Terminal

liblab init

This will create a file called liblab.config.json in your current directory.

Terminal

➜  my-api: liblab init
liblab.config.json created successfully
Run liblab build to generate your SDKs

Expand to see an example config file

{
  "sdkName": "test-sdk",
  "apiVersion": "1.0.0",
  "apiName": "test-api",
  "specFilePath": "spec.json",
  "languages": [
    "csharp",
    "go",
    "python",
    "typescript"
  ],
  "auth": [
    "bearer"
  ],
  "customizations": {
    "includeOptionalSnippetParameters": true,
    "authentication": {
      "access": {
        "prefix": "Bearer"
      }
    },
    "devContainer": false,
    "generateEnv": true,
    "inferServiceNames": false,
    "injectedModels": [],
    "license": {
      "type": "MIT"
    },
    "responseHeaders": false,
    "retry": {
      "enabled": true,
      "maxAttempts": 3,
      "retryDelay": 150
    }
  },
  "languageOptions": {
    "python": {
      "alwaysInitializeOptionals": false,
      "pypiPackageName": "",
      "githubRepoName": "",
      "ignoreFiles": [],
      "sdkVersion": "1.0.0",
      "liblabVersion": "2"
    },
    "typescript": {
      "bundle": false,
      "exportClassDefault": false,
      "httpClient": "fetch",
      "npmName": "",
      "npmOrg": "",
      "githubRepoName": "",
      "ignoreFiles": [],
      "sdkVersion": "1.0.0",
      "liblabVersion": "1"
    },
    "go": {
      "goModuleName": "github.com/swagger-api/swagger-petstore",
      "githubRepoName": "",
      "ignoreFiles": [],
      "sdkVersion": "1.0.0",
      "liblabVersion": "2"
    },
    "csharp": {
      "packageId": "",
      "githubRepoName": "",
      "ignoreFiles": [],
      "sdkVersion": "1.0.0",
      "liblabVersion": "2"
    }
  },
  "publishing": {
    "githubOrg": ""
  }
}

For your first spec, the important sections are:

• sdkName - The name of your SDK. This will be used as the name of the SDK package.
• specFilePath - The path to your API spec. This can be a local path or a URL.
• languages - The list of languages you want to generate SDKs for.
• auth - What authentication your API uses.

Open the file liblab.config.json in a text editor and update the values to match your API.

sdkName

Start by setting the sdkName to the name you want to use for your SDK. This will be used as the name of the SDK package.

For example, if you set the sdkName to exciting-soda, your Python SDK's pyproject.toml file would contain the following:

pyproject.toml

[project]
name = "excitingsoda"

While your TypeScript SDK would have a package.json with the following:

package.json

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

specFilePath

Next point the specFilePath to your spec. This can be a local file, or a URL. For example, if you have a local spec file called exciting-soda-openapi.yaml, you could copy this to the same folder as the config file and set the value to this file:

liblab.config.json

{
  "specFilePath": "./exciting-soda-openapi.yaml"
  ...
}

If this spec was online (for example a spec that is autogenerated by your API gateway), you could set the value to the URL:

liblab.config.json

{
  "specFilePath": "https://exciting.soda/openapi.json"
  ...
}

languages

The languages section is a list of languages you want to generate SDKs for. For example, if you want to generate SDKs for Python and TypeScript, you would set the value to:

liblab.config.json

{
  "languages": [
    "python",
    "typescript"
  ]
  ...
}

You can find the full list of supported languages in the language support guide.

auth

The auth section is used to specify the type of authentication your API uses. The authentication section of the customizations in the config file is also used to customize authentication. For example, if you are using bearer authentication, set this to bearer:

liblab.config.json

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

You can read more on authentication in our authentication guide

Generate your SDK

note

Before generating your SDK, you should validate your spec. This will ensure that your spec is valid and that liblab can generate an SDK from it. The liblab CLI has a validator you can use to ensure that your config file is valid and that your spec is ready to be used to generate an SDK. For this quickstart, we won't be validating the spec, instead we will skip validation.

If you want to read more on validation, check out the validation section of our CLI guide.

Now that your liblab config file is complete, you are ready to generate your SDK. To do this, run the following command:

Terminal

liblab build --skip-validation

This will generate your SDKs and docs. You will see a progress bar for each language, and a message when the SDKs and documentation are generated.

Terminal

✓ C# built
✓ Go built
✓ Java built
✓ Python built
✓ TypeScript built
Successfully generated SDKs downloaded. You can find them inside the "output" folder
Successfully generated SDK's for C#, TypeScript, Go, Python and Java ♡

The SDKs will be downloaded to a folder called output in your current project. The SDKs will be available to preview online, or to download as a zip file under https://app.liblab.com/apis/.

🎉🎉🎉   Congratulations, you have generated your first SDK!   🎉🎉🎉

Review and test your SDK

The SDKs will be in the output folder, with one folder per language. Each folder is designed to be deployed to source control such as GitHub and contains standard git files such as a .gitignore appropriate for the programming language, as well as a README.md with SDK documentation.

output/
├─ csharp
├─ go
├─ java
├─ python
├─ typescript
└─ terraform

Run an example

In each output folder there is an example folder containing a single, runnable example that calls the first API endpoint defined in the spec. This is designed to quickly show the SDK in use. In each example folder is an install script that installs the SDK and any dependencies, and a sample application you can run.

For example, in a Python SDK, you would run the following commands:

Terminal

cd output/python/examples
chmod +x ./install.sh
./install.sh

source ./.venv/bin/activate
python sample.py

This will make the install.sh file executable, then runs it. In the case of Python, this will create a virtual environment called .venv and will install the Python SDK into that environment. After this, you can activate the virtual environment and run the sample application.

Depending on the authentication you are using, you may need to set an environment variable containing an API key or bearer token. You can see the name of this environment variable in the sample application.

sdk.set_bearer_token(getenv("EXCITINGSODA_BEARER_TOKEN"))

Use the SDK in a devcontainer

Each SDK can optionally have a development container configuration, allowing you to open these inside a development container in IDEs such as Visual Studio Code. This is enabled by default and you can turn it off turn by changing the devContainer flag in your config file.

The container is configured with all the relevant dependencies, so once opened in a container you will be able to build the SDKs and run the examples without installing anything locally.

You can read more about development containers at containers.dev.

Documentation

In addition to the documentation in the README, the deployed docs site contains full API and SDK documentation, including how to access the API using curl as well as using all the programming languages generated.

Next steps

Now you have your SDK up and running 🎉.

To learn more about documentation and the SDK structure, check out SDK structure and documentation.

Otherwise, check out one of our hands-on tutorials to help you level up your SDKs.

End-to-end SDK generation and publishing with GitHub Actions

Automatically generate your SDK every time your API changes using GitHub Actions.

Go

Build a retrieval augmented generation (RAG) AI app using SDKs

Learn how to add RAG to your apps using Semantic Kernel and C# SDKs.

Go

Integrate SDK Snippets into your API Reference Documentation using Docusaurus

Learn how to add SDK documentation to an existing Docusaurus documentation site.

Go

Customize your SDK with hooks

Learn how to customize your SDK with hooks.

Go

Creating Python SDK Workflows with the Petstore API

Learn how to build and utilize SDK Workflows with liblab to enhance API integration.

Go

Create an SDK for a FastAPI

Learn how to build and utilize SDK Workflows with liblab to enhance API integration.

Go

Build a Python SDK with Streaming

Learn how to build and utilize an SDK with streaming.

Go

Redocly API docs integration

Learn how to integrate Redocly with liblab to generate enhanced API documentation.

Go

Build a TypeScript SDK with Pagination

Learn how to use the pagination feature to automate your queries from large data sets.

Go

liblab TypeScript SDK generator overview

Learn how to generate an SDK using the TypeScript v2 SDK and explore its new features.

Go

liblab Java SDK generator overview

Learn how to generate an SDK using the Java v2 SDK and explore its new features.

Go