Skip to main content

Generate code snippets and enhanced API spec

When you generate your SDK using the liblab build CLI command, the process also generates SDK documentation if the docs configuration option is set. By default, this option is an empty array, meaning no documentation is generated unless explicitly configured.

Control resources generation​

To turn on code snippets and the enhanced API spec generation, set the docs option in your liblab config file to snippets, enhancedApiSpec, or both.

liblab.config.json
{
    "docs": [
        "snippets",
        "enhancedApiSpec"
    ]
}

Remove the docs option if you don't want to generate these files.

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.

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"
            }
        }
    }

Generate enhanced API spec​

To generate the enhanced version of your API spec, run the liblab build command with enhancedApiSpec as one of the values in the docs option.

liblab.config.json
{
    "docs": [
        "enhancedApiSpec"
    ]
}

The generated enhanced API spec is created at output directory, together with the generated SDKs.

output
└── enhancedApiSpec.json
Last updated on