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 can automatically apply code samples to your base spec in the cloud, with no intervention required.

In the APIs tab of the dashboard, look for an entry marked as Combined Spec. When clicking into it, you will see a breakdown of the base spec and code samples overlays that were used to produce it.

You can easily configure one of these combined code sample specs as a public URL for documentation providers by visiting the Docs tab in the speakeasy dashboard.

Automatic CodeSample URLs not Available

automatic-code-samples-url-unavailable.png

If you do not see a Combined Spec in the dashboard, verify the following:

• In your workflow.yaml for each SDK you would like included:
  • The source (your OpenAPI document) must have a registry location specified.
  • The target (your SDK) must have a codeSamples section with a registry location specified.
• Your SDK must be generated with GitHub Actions. Ensure it has been generated and pushed within the last 10 days.
• Your SDK GitHub Action must either by in direct mode or have the sdk-publish action configured
• It is not necessary to actually publish your SDK to a package manager. But it is necesarry that release tagging is being completed by this action.

If you are really not ready to setup publishing, you can temporarily setup the following tagging action in each of your SDK repos.

.github/workflows/tagging.yam

name: Speakeasy Tagging
permissions:
    checks: write
    contents: write
    pull-requests: write
    statuses: write
"on":
    push:
        branches:
            - main
        paths: []
    workflow_dispatch: {}
jobs:
    tag:
        uses: speakeasy-api/sdk-generation-action/.github/workflows/tag.yaml@v15
        with:
            registry_tags: main
        secrets:
            github_access_token: ${{ secrets.GITHUB_TOKEN }}
            speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}

End result:

• In the APIs tab of the Speakeasy dashboard, you should see:
  • An entry for your base OpenAPI document (e.g. my-source)
  • A code samples overlay (e.g. my-source-{lang}-code-samples) for each SDK you want in your final document
  • Each of these must have a main tag on any revision (this is why GitHub Actions is required)

Manually Applying Code Samples to Your OpenAPI Document

If you are not eligible to use Speakeasy’s automatic code sample URLs or you would prefer to manually set up code samples yourself.

You can always apply code samples via the CLI.

Code samples can be applied to your OpenAPI document like any other overlay. The Speakeasy CLI makes this easy:

speakeasy overlay apply --overlay code-samples.yaml --schema {{your-spec.yaml}} --out {{output-spec.yaml}}

You can also 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.