Skip to main content

API and SDK documentation overview

As part of the SDK generation process, liblab generates API and SDK documentation for all the configured languages. This documentation is available either as a static site with full API and SDK documentation or as SDK snippets that can be integrated into your own documentation platform. Additionally, liblab offers the ability to enhance your OpenAPI spec by embedding SDK code samples, making it easier for developers to understand and integrate with your API.

SDK documentation uses the descriptions and examples from your API spec. The better the quality of your API spec, the higher the quality of the generated SDK documentation.

SDK Snippets​

SDK Snippets are code examples in either markdown or JSON that demonstrate how to call all the endpoints in your API specification. liblab generates snippets for all the configured and supported SDK languages. The generated snippets are included in the generated SDKs.

Supported SDK languages and versions:

TypeScript v1TypeScript v2Java v1Java v2Python v1Python v2C#GoPHP
❌✅❌✅❌✅✅✅✅

The liblab SDK snippets include the following features:

  • Code snippets for all supported SDK languages.
  • Snippets are created as markdown (one file per endpoint) or JSON (all endpoints in a single file).
  • Snippets are generated with the SDK and can be integrated into your own documentation platform using your CI/CD pipeline.

To generate SDK snippets, add the snippets option in the docs configuration of your liblab configuration file. The snippet format can be customized using the documentation/snippets/format option.

The following code block presents a configuration example to generate the snippets using json format:

liblab.config.json
{
  ...
  "docs": [
    "snippets"
  ],
  "customizations": {
    "documentation": {
      "snippets": {
        "format": "json"
      }
    }
  },
  ...
}

Below are examples of generated snippets in both markdown and JSON formats:

snippets.md
  ˋˋˋmd
  from exciting_soda import ExcitingSoda,
  Environment

  sdk = ExcitingSoda(
  base_url=Environment.DEFAULT.value
  )

  result = sdk.sodas.list_sodas()

  print(result)
  ˋˋˋ

Enhanced OpenAPI spec​

liblab enhances your OpenAPI spec by embedding SDK code samples, allowing seamless integration with API documentation providers. The enhanced OpenAPI spec includes code samples from the newly generated SDK, added at the operation level, so developers can easily understand how to interact with your API using the SDK in real-world scenarios.

To generate the enhanced OpenAPI spec, add the enhancedApiSpec option in the docs configuration of your liblab configuration file. You can specify the output name and format of the enhanced OpenAPI spec using the customizations/documentation/enhancedApiSpec/customOutputName option. The output can be in json or yaml. If not specified, the default is enhancedApiSpec.json.

The following code block presents a configuration example to generate the enhanced OpenAPI spec:

liblab.config.json
{
  "docs": [
    "enhancedApiSpec"
  ],
  "customizations": {
    "documentation": {
      "enhancedApiSpec": {
        "customOutputName": "new-spec.yaml"
      }
    }
  }
  ...
}

Structure of the Enhanced Spec​

The enhancement modifies your OpenAPI spec at the operation level. When you run liblab build to generate the SDKs, liblab will create the SDKs and also inject the generated code snippets into your OpenAPI spec. Once the build is completed, liblab adds the SDK code snippets into the x-codeSamples property of each operation object in your OpenAPI spec.

A typical modification would look like this:

{
  "x-codeSamples": [
    {
      "lang": "go",
      "source": "import (\n  \"fmt\"\n  \"encoding/json\"\n  \"github.com/swagger-api/swagger-petstore/pkg/testsdkconfig\"\n  \"github.com/swagger-api/swagger-petstore/pkg/testsdk\"\n  \"github.com/swagger-api/swagger-petstore/pkg/pets\"\n)\n\nconfig := testsdkconfig.NewConfig()\nclient := testsdk.NewTestSdk(config)\n\n\nparams := pets.ListPetsRequestParams{}\n\n\nresponse, err := client.Pets.ListPets(context.Background(), params)\nif err != nil {\n  panic(err)\n}\n\nfmt.Print(response)"
    }
  ]
  ...
}

Where:

  • lang: Specifies the language of the SDK.
  • source: Contains the SDK code snippet.

liblab will not overwrite existing code samples in x-codeSamples for different languages but will replace snippets for languages it generated. If the x-codeSamples property does not exist or if certain SDK languages are missing, liblab will populate it with newly generated snippets.

Documentation provider integration

Check out the Redocly API docs integration tutorial to learn how to make the enhanced OpenAPI spec available for your customers.

API documentation​

You can use liblab to generate static API documentation that includes detailed descriptions, code examples from your API spec, and SDK snippets for all supported languages. The generated documentation also includes curl examples for making direct API calls.

Supported SDK languages and versions:

TypeScript v1TypeScript v2Java v1Java v2Python v1Python v2C#GoPHP
✅❌✅❌✅❌❌❌❌

SDK documentation preview SDK documentation preview

The liblab-generated API documentation includes the following features:

  • Code snippets for all supported SDK languages, as well as curl commands.
  • Descriptions and examples directly from your API spec.
  • Support for markdown format.
  • Hosted documentation on liblab, or you can download and host it yourself.

To generate API documentation, add the api option in the docs configuration of your liblab configuration file. Below you find an example of how to do it:

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

What’s Next?​

To learn more about generating and making your documentation available to your customers, check out the following documentation pages:

Last updated on