Generate documentation with the liblab CLI
When you generate your SDK with the liblab build CLI command, SDK documentation is also generated if you have any options set in the docs config file option options. This option defaults to an empty array, with no documentation generated.
Control documentation generation
To turn on documentation generation, set the docs option in your liblab config file to api, snippets, or both.
{
"docs": [
"api",
"snippets"
]
}
To turn off documentation generation, remove this option.
Generate SDK snippets
To generate SDK snippets, run the liblab build command with snippets as one of the values in the docs option.
{
"docs": [
"snippets"
]
}
The generated SDK snippets are in a subfolder of the generated SDK. For example, if you generate a C# SDK with snippets, the C# snippets will be in output/csharp/Documentation/snippets.
output
└── csharp
└── Documentation
└── snippets
Markdown snippets
Markdown snippets consist of one file per endpoint and HTTP request method, named as <endpoint>-<method>, with path parameters included in the endpoint name. For example, if you have a GET and POST method for sodas, and a GET method for sodas/{soda-id}, you would get the following 3 markdown files created:
Documentation
└── snippets
├── sodas-get.md
├── sodas-post.md
└── sodas-{soda-id}-get.md
Each markdown file contains a single markdown section tagged with the SDK language, and a code snippet that shows creating the SDK client and calling the endpoint using values from the examples in your OpenAPI spec. If no examples are provided, the code snippet will use random placeholder values.
For example, for the sodas-get.md file for Python, you might get the following snippet:
ˋˋˋpython
from exciting_soda import ExcitingSoda, Environment
sdk = ExcitingSoda(
base_url=Environment.DEFAULT.value
)
result = sdk.sodas.list_sodas(limit=100)
print(result)
ˋˋˋ
These markdown files can be copied from the generated SDKs into your own documentation, matching the structure of your API documentation.
JSON snippets
JSON snippets consist of a single JSON document that contains all the samples for all endpoints and HTTP request methods, as well as sample code for configuring environments and authentication.
Documentation
└── snippets
└── snippets.json
{
"endpoints": {
"/sodas": {
"get": "from exciting_soda import ExcitingSoda, Environment\n\nsdk = ExcitingSoda(\n
api_key=\"YOUR_API_KEY\",\n api_key_header=\"YOUR_API_KEY_HEADER\",\n
base_url=Environment.DEFAULT.value\n)\n\nresult = sdk.sodas.list_sodas(limit=100)\n\n
print(result)\n",
}
}
}
This is designed to be parsed by your documentation tooling to display the code snippets in your API documentation.
Generate API documentation
To generate API documentation, run the liblab build command with api as one of the values in the docs option.
{
"docs": [
"api"
]
}
This generates a static HTML site with API documentation, along with SDK examples.
✓ Doc built
SDKs downloaded successfully. You can find them inside the "output" folder
Action Link
──────── ─────────────────────────────────────────────────────────────────────────────────────────────────────────────
Preview https://docs.liblab.com/liblab/preview/1ebe91ad-e08e-40ea-b05c-1808bc2dfcd3
Download https://prod-liblab-api-stack-docs.s3.us-east-1.amazonaws.com/1ebe91ad-e08e-40ea-b05c-1808bc2dfcd3/bundle.zip
Two links are provided in the CLI output - a link to preview the docs, and a link to download the HTML as a zip file that you can host yourself.
This preview is only temporary to review the docs, and should not be used for hosting the docs long term as these will be removed after a short while.
You can select the SDK language from the drop down at the top right. Select cURL to see the API documentation, otherwise select the SDK language, such as Java, Python or TypeScript.
Customize documentation generation
Some of the generated documentation can be configured using your liblab config file on a per-SDK basis. Other configuration can happen at an organization level using settings in the liblab portal.
Generic documentation settings
In your liblab config file, you can configure the following settings for your documentation. See the documentation for each of these config file options for more details.
includeOptionalSnippetParameters- this option determines if optional and deprecated parameters should be included in the code snippets and API documentation or not.
SDK snippets settings
In your liblab config file, you can configure the following settings for your SDK snippets. See the documentation for each of these config file options for more details.
-
documentation/snippets/format- this option determines the format of SDK snippets. Valid values arejsonandmarkdown.liblab.config.json{
"docs": [
"snippets"
]
"documentation": {
"snippets": {
"format": "markdown"
}
}
}
API documentation settings
Organization level documentation settings
From the liblab portal, you can configure the following settings for your documentation at an organization level:
These changes will affect newly created documentation and will not affect existing documentation.
Organization logo
Your organization logo is displayed in the top left corner of the documentation. This is set in the organization settings and is applied to all documentation within the organization. Only users with the Admin role can set the organization logo.
To set the logo, follow these steps:
- From the liblab portal, select the Settings menu
- Add the URL of your logo to the Logo (URL) field
- Select the Save button to save the changes
