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"
],
"createDocs": false,
"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": "axios",
"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.
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 you will get a Python package called excitingsoda. This is the pyproject.toml file for the Python package:
[project]
name = "excitingsoda"
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 you have a liblab config file, 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
✓ Terraform built
✓ TypeScript built
✓ Doc built
SDKs downloaded successfully. You can find them inside the "output" folder
Action Link
──────── ──────────────────────────────────────────────────────────────────────────────
Preview <link>
Download <link>
? Would you like to approve and publish these docs now? (Y/n)
The SDKs will be downloaded to a folder called output in your current directory. The SDKs will be available to preview online, or to download as a zip file using the links provided. You will also be asked of you want to approve the docs and publish them to the liblab docs site. You can learn more about this in our SDK documentation guide.
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 code control, such as in GitHub, and contains standard git files such as a .gitignore appropriate for the 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. To enable this, turn on 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 languages generated.
Next steps
Now you have your SDK, check out these tutorials to learn more and do more with liblab.
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.