Overview

You can now integrate Speakeasy-generated code snippets from your SDKs directly into your Mintlify API reference documentation. SDK usage snippets are shown in the interactive playground (opens in a new tab) of your Mintlify-powered documentation.

https://mintlify.com/docs/api-playground/overview

Set Up Options

You can set up the integration between Speakeasy and Mintlify in three ways:

Using the setup wizard (recommended).
Using the interactive CLI.
Manually.

Using the Setup Wizard

In the Speakeasy dashboard, go to the Docs tab and select the "Mintlify" card.

app.speakeasy.com

Choose the SDKs you want to integrate with Mintlify. Ensure all selected SDKs are generated from the same OpenAPI schema.

app.speakeasy.com

Click Next and then enter the URL of your Mintlify repository. If prompted, install the Speakeasy GitHub app to configure the integration.

app.speakeasy.com

The integration will trigger several GitHub actions in the source SDK repositories to generate the code samples. Once these actions are complete, another action will run in the Mintlify repository to pull in the code samples. In future, code samples will be automatically generated alongside your SDK.

Interactive CLI Setup

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.

Add your SPEAKEASY_API_KEY as a repository secret to your Mintlify repo under Settings > Secrets & Variables > Actions. Find your Speakeasy API key in the Speakeasy dashboard under the API Keys tab.
Update your mint.json file to include the following:


{
  ...
  "openapi": "./path/to/your/openapi.yaml",
  ...
}

For more information on using mint.json to manage your global configuration, please see here (opens in a new tab).

Manual Setup

Alternatively, you can manually set up the following files.

In your Speakeasy SDK repositories, add the following to the targets section of the .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
            registry:
                location: registry.speakeasyapi.dev/<org>/<workspace>/my-typescript-sdk-code-samples

In your Mintlify repo, add the following files:

.speakeasy/workflow.yaml


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: {}

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

Add your SPEAKEASY_API_KEY as a repository secret to your Mintlify repo under Settings > Secrets & Variables > Actions. Find your Speakeasy API key in the Speakeasy dashboard under the API Keys tab.
Update your mint.json file to include the following:


{
  ...
  "openapi": "./path/to/your/openapi.yaml",
  ...
}

For more information on using mint.json to manage your global configuration, please see Mintlify's documentation (opens in a new tab).

Customize Code Samples

Speakeasy offers a few ways to customize code samples, specifically by overriding the default values for lang and label, which different docs providers use in different ways. Depending on your provider, you may want to customize these values.

By default, the output code sample for each operation will look like this:


- lang: typescript # The language of the target SDK
  label: getApis # The operation ID of the code snippet
  source: <code snippet>

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