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.
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.
- Choose the SDKs you want to integrate with Mintlify. Ensure all selected SDKs are generated from the same OpenAPI schema.
- Click Next and then enter the URL of your Mintlify repository. If prompted, install the Speakeasy GitHub app to configure the integration.
- 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 sourcesspeakeasy 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:
- In your Mintlify repo, add the following files:
-
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