Quickstart - Generate an SDK from your OpenAPI spec
This quickstart walks you through generating an SDK from your OpenAPI spec using liblab.
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:
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:
liblab init
This will create a file called liblab.config.json
in your current directory.
➜ 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:
[project]
name = "excitingsoda"
While your TypeScript SDK would have a package.json
with the following:
{
"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:
{
"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:
{
"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:
{
"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
:
{
"auth": [
"bearer"
]
...
}
You can read more on authentication in our authentication guide
Generate your SDK
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:
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.
✓ 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/.
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:
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.
Automatically generate your SDK every time your API changes using GitHub Actions.
Learn how to add RAG to your apps using Semantic Kernel and C# SDKs.
Learn how to add SDK documentation to an existing Docusaurus documentation site.
Learn how to customize your SDK with hooks.
Learn how to build an SDK to control a llama in a game.
Learn how to build and utilize SDK Workflows with liblab to enhance API integration.
Learn how to build and utilize SDK Workflows with liblab to enhance API integration.
Learn how to build and utilize an SDK with streaming.
Learn how to integrate Redocly with liblab to generate enhanced API documentation.
Learn how to use the pagination feature to automate your queries from large data sets.
Learn how to generate an SDK using the TypeScript v2 SDK and explore its new features.
Learn how to generate an SDK using the Java v2 SDK and explore its new features.