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. SDK usage snippets are shown in the interactive playground of your Mintlify-powered documentation.

Speakeasy SDK Repository Changes

In your Speakeasy SDK repos, add the following to the targets section of your .speakeasy/workflow.yaml file to ensure code samples are automatically produced alongside SDK generations.

.speakeasy/workflow.yaml

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

Code samples will be generated in the form of an OpenAPI overlay file that will be used in the Mintlify docs repository.

Mintlify Docs Repository Changes

The workflow files produced will automatically bundle your source OpenAPI spec and Speakeasy code samples into a single output file, openapi.yaml. Mintlify will use this output file when constructing your API Reference.

Interactive CLI Set Up

Run the following commands to set up the .speakeasy/workflow.yaml and .github/workflows/sdk_generation.yaml files through the interactive Speakeasy CLI.

speakeasy configure sources
speakeasy configure github

Set up your source spec. The source spec is the OpenAPI spec that code samples will be generated for, and it’s often the same specification used to power Mintlify docs.

Add the overlay created by Speakeasy to inject code snippets into your spec.

Provide a name and path for the OpenAPI spec. This will be the final spec used by Mintlify.

Finally, Add your SPEAKEASY_API_KEY as a repository secret to your Mintlify repo under Settings > Secrets & Variables > Actions. Find the Speakeasy API key in the Speakeasy dashboard under the API Keys tab.

Manual Set Up

Alternatively, you can manually set up the following files in your Mintlify docs repo.

.speakeasy/workflow.yaml

workflowVersion: 1.0.0
sources:
  docs-source:
    inputs:
      - location: {{your_api_spec}} # local or remote references supported
    overlays:
      - location: https://raw.githubusercontent.com/{{your_sdk_repo_1}}/codeSamples.yaml
      - location: https://raw.githubusercontent.com/{{your_sdk_repo_2}}/codeSamples.yaml
      - location: https://raw.githubusercontent.com/{{your_sdk_repo_3}}/codeSamples.yaml
    output: openapi.yaml
targets: {}

.speakeasy/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, make sure you add your SPEAKEASY_API_KEY as a repository secret to your Mintlify repo under Settings > Secrets & Variables > Actions. Find the Speakeasy API key in the Speakeasy dashboard under the API Keys tab.