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.

liblab.config.json

{
    "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.

liblab.config.json

{
    "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:

sodas-get.md

ˋˋˋ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

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.

liblab.config.json

{
    "docs": [
        "api"
    ]
}

This generates a static HTML site with API documentation, along with SDK examples.

Terminal

✓ 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.

note

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 are json and markdown.

  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:

• Organization logo

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:

1. From the liblab portal, select the Settings menu
2. Add the URL of your logo to the Logo (URL) field
3. Select the Save button to save the changes