Speakeasy

Automate your SDK usage snippets in the API playground

Speakeasy allows you to automatically generate SDK code snippets and display them in your API playground. Here’s how to set it up:

1. Configure Your SDK Repository

Add the following to your .speakeasy/workflow.yaml file in your SDK repository:

.speakeasy/workflow.yaml

targets:
  my-target:
    target: typescript
    source: my-source
    codeSamples:
      output: codeSamples.yaml

2. Set Up Your Docs Repository

The easiest way to set up your docs repository is through the Speakeasy CLI:

speakeasy configure sources
speakeasy configure github

Follow the prompts to:

1. Set up your source OpenAPI spec
2. Add the code snippet overlay
3. Configure the output specification path

3. Add Your API Key

Add your SPEAKEASY_API_KEY as a repository secret:

1. Go to your Mintlify repository’s Settings > Secrets & Variables > Actions
2. Add the key from your Speakeasy dashboard’s API Keys tab

Manual Setup (Alternative)

If you prefer manual setup, create these files in your docs repository:

.speakeasy/workflow.yaml

workflowVersion: 1.0.0
sources:
  docs-source:
    inputs:
      - location: {{your_api_spec}}
    overlays:
      - location: https://raw.githubusercontent.com/{{your_sdk_repo}}/codeSamples.yaml
    output: openapi.yaml
targets: {}

.github/workflows/sdk_generation.yaml

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
      speakeasy_version: latest
    secrets:
      github_access_token: ${{ secrets.GITHUB_TOKEN }}
      speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}