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
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:
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
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.
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
exciting-soda you will get a Python package called
excitingsoda. This is the
pyproject.toml file for the Python package:
name = "excitingsoda"
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:
If this spec was online (for example a spec that is autogenerated by your API gateway), you could set the value to the URL:
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:
You can find the full list of supported languages in the language support guide.
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
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.
✓ Java built
✓ Python built
✓ Typescript built
✓ Doc built
SDKs downloaded successfully. You can find them inside the "output" folder
? 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 docs 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.
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:
chmod +x ./install.sh
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.
Use the SDK in a devcontainer
Each SDK has a development container configuration, allowing you to open these inside a development container in IDEs such as Visual Studio Code. 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.
This container is configured so when you run or debug in VS Code, the example will be run.
You can read more about development containers at containers.dev.
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.
Now you have your SDK, check out these tutorials to learn more and do more with liblab.