diff --git a/integrations/sdks/speakeasy.mdx b/integrations/sdks/speakeasy.mdx index d45628bed..89ac09eb9 100644 --- a/integrations/sdks/speakeasy.mdx +++ b/integrations/sdks/speakeasy.mdx @@ -3,95 +3,62 @@ title: Speakeasy description: 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](https://mintlify.com/docs/api-playground/overview) of your Mintlify-powered documentation. +Autogenerated code snippets from Speakeasy SDKs can be integrated directly into Mintlify API reference documentation. SDK usage snippets are shown in the [interactive playground](https://mintlify.com/docs/api-playground/overview) of Mintlify-powered documentation sites. -## Speakeasy SDK Repository Changes + + ![Speakeasy code snippets with + Mintlify.](../assets/code-samples/mintlify-with-speakeasy-openapi.png) + -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. -```yaml .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](https://www.speakeasyapi.dev/openapi/overlays) 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. +## Prerequisites -### 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. - -```bash -speakeasy configure sources -speakeasy configure github -``` +To integrate Mintlify with Speakeasy, you'll need the following: -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. + - A [Mintlify documentation repository](https://mintlify.com/docs/quickstart#creating-the-repository). + - A Speakeasy-generated SDK with a configured [automated code sample URL](/docs/code-samples/automated-code-sample-urls). -![](/images/speakeasy-1.webp) +## Setting up the integration -Add the overlay created by Speakeasy to inject code snippets into your spec. + -![](/images/speakeasy-2.webp) +### Update the `mint.json` configuration file -Provide a name and path for the OpenAPI spec. This will be the final spec used by Mintlify. +Add the combined spec URL to **Anchors** or **Tabs** in the `mint.json` file of a Mintlify repository. Anchors are displayed as a list of links on the left side of the documentation, while Tabs are displayed as tabs along the top of the documentation. -![](/images/speakeasy-3.webp) +Add the combined spec URL to **Anchors** by updating the `anchor` field in the `mint.json` file as follows: -Finally, Add your `SPEAKEASY_API_KEY` as a repository secret to your Minlify 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. - - -```yaml .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: {} +```json mint.json +{ + "anchors": [ + { + "name": "API Reference", + // !mark + "openapi": "SPEAKEASY_COMBINED_SPEC_URL", + "url": "api-reference", + "icon": "square-terminal" + } + ] +} ``` -```yaml .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 }} +Add the combined spec URL to **Tabs** by updating the `tab` field in the `mint.json` file as follows: + +```json mint.json +{ + "tabs": [ + { + "name": "API Reference", + "url": "api-reference", + // !mark + "openapi": "SPEAKEASY_COMBINED_SPEC_URL" + } + ] +} ``` -Finally, make sure you add your `SPEAKEASY_API_KEY` as a repository secret to your Minlify repo under `Settings > Secrets & Variables > Actions`. Find the Speakeasy API key in the Speakeasy dashboard under the **API Keys** tab. +Speakeasy-generated code snippets can now be viewed in the Mintlify API reference documentation. See the code snippets in action in the [interactive playground](https://mintlify.com/docs/api-playground/overview) of the Mintlify-powered documentation site. + +## Next steps + +Mintlify offers flexible customization options for API references generated from OpenAPI documents. For more information, refer to the [Mintlify documentation](https://mintlify.com/docs/api-playground/openapi/setup).