Skip to main content

SDK code snippets for API documentation

As part of the SDK generation process, liblab generates code snippets from SDKs you can add to your 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 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:

TypeScriptJavaPythonC#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​

Supported SDK languages and versions:

TypeScriptJavaPythonC#GoPHP
✅✅✅✅✅✅

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 tutorials to learn how to make the enhanced OpenAPI spec available for your customers:

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