Speakeasy

Automate your SDK usage snippets in the API playground

Integrate Speakeasy-generated code snippets from your SDKs into your Mintlify API reference documentation to display SDK usage snippets in the interactive playground.

SDK Repository Setup

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

.speakeasy/workflow.yaml

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

Mintlify Repository Setup

You can set up Speakeasy integration either through the CLI or manually.

Option 1: CLI Setup

1. Run the setup commands:

speakeasy configure sources
speakeasy configure github

2. Follow the CLI prompts to:
   • Set up your source OpenAPI spec
   • Add the Speakeasy overlay for code snippets
   • Configure the output spec path

Option 2: Manual Setup

Create the following files in your Mintlify docs repo:

.speakeasy/workflow.yaml

workflowVersion: 1.0.0
sources:
  docs-source:
    inputs:
      - location: {{your_api_spec}}
    overlays:
      - location: https://raw.githubusercontent.com/{{your_sdk_repo_1}}/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 }}

Finally, add your SPEAKEASY_API_KEY as a repository secret under Settings > Secrets & Variables > Actions. You can find the key in the Speakeasy dashboard under API Keys.