API and SDK documentation overview

As part of SDK generation, liblab can generate API and SDK documentation for all the supported languages you have configured. Documentation is available as a static site with API and SDK documentation, or as SDK snippets that you can integrate into your own documentation platform.

SDK documentation uses the descriptions and examples from your API spec. The better the quality of your API spec, the better the quality of the SDK documentation that is created.

SDK snippets

SDK snippets are code snippets as either markdown or JSON that contain examples of how to call all the endpoints in your API specification. SDK snippets are generated for all the supported SDK languages you have configured, and are included in the generated SDK.

Supported SDK languages and versions:

TypeScript v1	TypeScript v2	Java	Python v1	Python v2	C#	Go	PHP
❌	❌	❌	❌	✅	✅	✅	✅

soda-get.md

ˋˋˋmd
from exciting_soda import ExcitingSoda,
 Environment

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

result = sdk.sodas.list_sodas()

print(result)
ˋˋˋ

snippets.json

{
  "endpoints": {
    "/sodas": {
      "get": "from exciting_soda import
ExcitingSoda, Environment\n\nsdk =
ExcitingSoda(\n
base_url=Environment.DEFAULT.value\n)\n\n
result = sdk.sodas.list_sodas()\n\n
print(result)\n"
    }
  }
}

SDK snippets are generated when you have the snippets option specified in the docs option of your liblab configuration file. The format is controlled using the documentation/snippets/format option.

liblab.config.json

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

SDK snippets features

SDK snippets include the following features:

• Code snippets for all supported SDK languages you have created
• Create snippets as markdown with one file per endpoint, or JSON for all endpoints in one file
• Snippets generated with your SDK, and can be integrated into your own documentation platform in your CI/CD pipeline

API documentation

liblab can generate API documentation as a static site that includes documentation for all the endpoints in your API specification. The documentation includes descriptions and examples from your API spec, as well as code snippets for curl, and all the supported SDK languages you have created.

Supported SDK languages and versions:

TypeScript v1	TypeScript v2	Java	Python v1	Python v2	C#	Go	PHP
✅	❌	✅	✅	❌	❌	❌	❌

API documentation is generated when you have the api option specified in the docs option of your liblab configuration file.

liblab.config.json

{
  "docs": [
    "api"
  ],
  ...
}

note

API documentation used to be controlled by the createDocs config file option. This has been deprecated in favor of the docs options.

API documentation features

The API documentation includes the following features:

• Code snippets for all SDK languages you have created, as well as using curl to call the API directly
• Documentation and examples taken from your API specification
• Support for markdown
• liblab hosted documentation, or you can download it and host it yourself

Get started

• Generate documentation with the liblab CLI
• View and host API documentation