Speakeasy
Automate your SDK usage snippets in the API playground
Speakeasy SDK Repository Changes
In your Speakeasy SDK repos add the following addition to the targets section of your .speakeasy/workflow.yaml
file to ensure code samples automatically get produced alongside your SDK generations.
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 together 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 Setup
Run the following commands to setup your .speakeasy/workflow.yaml
and .github/workflows/sdk_generation.yaml
files through Speakeasy’s interactive CLI.
speakeasy configure sources
speakeasy configure github
Set up your source spec. This is the OpenAPI spec that you want to generate code samples for. Often it is the same specification used to power your Mintlify docs.
We’ll now add the overlay created by Speakeasy to inject code snippets into your spec.
Finally provide name and path for your output openapi spec. This will the final spec used by Mintlify.
Lastly, make sure you add your SPEAKEASY_API_KEY
as a repository secret to your Minlify repo under Settings > Secrets & Variables > Actions. This can be found in your Speakeasy dashboard API Keys tab.
Manual Setup
Alternatively your can manually setup the following files in your Mintlify docs repo.
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: {}
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 }}
Lastly, make sure you add your SPEAKEASY_API_KEY
as a repository secret to your Minlify repo under *Settings > Secrets & Variables > Actions. This can be found in your Speakeasy dashboard API Keys tab.
Was this page helpful?