Speakeasy

Automate your SDK usage snippets in the API playground

You can integrate Speakeasy-generated code snippets from your SDKs directly into your Mintlify API reference documentation. These snippets appear in the interactive playground of your documentation.

Setup Steps

1. Configure SDK Repository Add the following to your .speakeasy/workflow.yaml file in your SDK repos:

.speakeasy/workflow.yaml

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

2. Set Up Mintlify Repository

   Choose one of these methods:

   Option A: Interactive Setup (Recommended)

   Run these commands:

   speakeasy configure sources
   speakeasy configure github
   

   Follow the prompts to set up your source spec and configure the code snippet overlay.

   Option B: Manual Setup

   Create two 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 }}
   

3. Add API Key Add your SPEAKEASY_API_KEY as a repository secret in your Mintlify repo under Settings > Secrets & Variables > Actions. You can find the key in the Speakeasy dashboard under the API Keys tab.