Generating Code Samples for your SDK

On this page, we cover how code sample generation for an SDK works and how it can be applied to an OpenAPI document.

What is the code samples extension?

Many API documentation providers provide code snippets in multiple languages to help developers understand how to use the API. However, these snippets may not correspond to a usage snippet from an existing SDK provided by the API, which reduces the value of the API documentation and can lead to inconsistent integrations, depending on whether a user discovers the API docs or the SDK first.

The x-codeSamples (previously called x-code-samples) extension is a widely accepted spec extension that enables the addition of custom code samples in one or more languages to operation IDs in your OpenAPI specification. When custom code samples are added using the code samples extension, documentation providers will render the usage snippet in the right-hand panel of the documentation page:

For a full breakdown of the code samples extension, see our guide.

Configuring Code Samples

Speakeasy provides code samples in the form of overlays. This ensures that your code samples can be trivially applied to your OpenAPI document without needing to upstream the changes. This is configured in your workflow file, as follows:

# ...
targets:
  my-target:
    target: typescript
    source: my-source
    codeSamples:
      output: code-samples.yaml # Optional, if you would like a local copy of your code samples to be produced
      registry:
        location: registry.speakeasy.com/my-org/my-workspace/my-source-typescript-code-samples
      blocking: false # Optional, defaults to true if not present

In the above example, a code samples overlay containing Typescript usage snippets for all operations in the my-source OpenAPI document will be generated and written to code-samples.yaml as well as pushed to the Speakeasy registry.

Why use the registry?

Speakeasy will automatically load code samples that are pushed to the Registry and apply them to your OpenAPI document. This saves you from having to manually configure a workflow to integrate your code samples into your base document. Removing the registry section from your workflow file will disable this feature and require you to manually apply code samples to your OpenAPI document.

Overrides

To override the lang and label values, you can add either or both of the following options to the codeSamples section in your workflow.yaml file:

targets:
  my-target:
    codeSamples:
      # ...
      langOverride: <any string> # set `lang` to this value in all code samples
      labelOverride:
        omit: true # omit the label field entirely from the output
        # OR
        fixedValue: <any string> # set the label to this value in all code samples

Styles

For certain documentation providers like ReadMe, you will need to override the default style of code samples in your OpenAPI spec. You can simply do that by modifying the following option in the codeSamples section of your workflow.yaml file

targets:
  my-target:
    codeSamples:
      # ...
      style: readme # Default is 'standard'

Automatic CodeSample URLs

For paid accounts Speakeasy’s most elegant solution for exposing code samples to documentation providers is through our automated code sample URLs product.

For a full breakdown of the feature, see our guide.

Manually Applying Code Samples to Your OpenAPI Document

If you would prefer you can always manually set up code sample integrations yourself. You can manually pull together code sample images in your own repository with a simple workflow.

workflowVersion: 1.0.0
speakeasyVersion: latest
sources:
  docs-source:
    inputs:
      - location: { { your_api_spec } } # local or remote references supported
    overlays:
      - location: registry.speakeasyapi.dev/<org>/<workspace>/my-typescript-sdk-code-samples # location of the code samples from previous step
      - location: registry.speakeasyapi.dev/<org>/<workspace>/my-go-sdk-code-samples
      - location: registry.speakeasyapi.dev/<org>/<workspace>/my-python-sdk-code-samples
    output: openapi.yaml
targets: {}

name: Generate
permissions:
  checks: write
  contents: write
  pull-requests: write
  statuses: write
"on":
  workflow_dispatch:
    inputs:
      force:
        description: Force generation of SDKs
        type: boolean
        default: false
  schedule:
    - cron: 0 0 * * *
jobs:
  generate:
    uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15
    with:
      force: ${{ github.event.inputs.force }}
      mode: pr
    secrets:
      github_access_token: ${{ secrets.GITHUB_TOKEN }}
      speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}

Now you can simply run speakeasy run. If you use registry references, the source and code samples will always be up to date with the main branch of your SDK repos.