diff --git a/images/speakeasy/copy-combined-spec-url.png b/images/speakeasy/copy-combined-spec-url.png new file mode 100644 index 000000000..4efae51d0 Binary files /dev/null and b/images/speakeasy/copy-combined-spec-url.png differ diff --git a/images/speakeasy/mintlify-with-speakeasy-openapi.png b/images/speakeasy/mintlify-with-speakeasy-openapi.png new file mode 100644 index 000000000..c11eed939 Binary files /dev/null and b/images/speakeasy/mintlify-with-speakeasy-openapi.png differ diff --git a/images/speakeasy/openapi-registry-and-combined-spec.png b/images/speakeasy/openapi-registry-and-combined-spec.png new file mode 100644 index 000000000..710148ded Binary files /dev/null and b/images/speakeasy/openapi-registry-and-combined-spec.png differ diff --git a/integrations/sdks/speakeasy.mdx b/integrations/sdks/speakeasy.mdx index d45628bed..5c20d6ba3 100644 --- a/integrations/sdks/speakeasy.mdx +++ b/integrations/sdks/speakeasy.mdx @@ -1,97 +1,76 @@ --- -title: Speakeasy -description: Automate your SDK usage snippets in the API playground +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](/api-playground/overview) of Mintlify-powered documentation sites. -## Speakeasy SDK Repository Changes + +![A Mintlify API playground with Speakeasy code snippets.](/images/speakeasy/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. +## Prerequisites -```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 +To integrate Mintlify with Speakeasy, you'll need the following: -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. + - A [Mintlify documentation repository](/quickstart#creating-the-repository). + - A Speakeasy-generated SDK with a configured [automated code sample URL](https://www.speakeasy.com/docs/code-samples/automated-code-sample-urls). -### 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 -``` +## Setting up the integration -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. +To integrate Speakeasy with Mintlify, you must get the API's combined spec public URL from the registry and update your `docs.json` configuration file. -![](/images/speakeasy-1.webp) +### Get the API's combined spec public URL from the registry -Add the overlay created by Speakeasy to inject code snippets into your spec. +Navigate to your [Speakeasy Dashboard](https://app.speakeasy.com) and open the **API Registry** tab. Open the `*-with-code-samples` entry for the API. -![](/images/speakeasy-2.webp) + +![Screenshot of the Speakeasy API Registry page. The API Registry tab is emphasized with a red square and the number 1 and the entry for the API is emphasized with a red square and the number 2.](/images/speakeasy/openapi-registry-and-combined-spec.png) + -Provide a name and path for the OpenAPI spec. This will be the final spec used by Mintlify. + + If the entry is not labeled **Combined Spec**, ensure that the API has an [automatic code sample URL](https://www.speakeasy.com/docs/code-samples/automated-code-sample-urls) configured. + -![](/images/speakeasy-3.webp) +From the registry entry's page, copy the provided public URL. -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. + +![Screenshot showing the combined spec registry entry with the copy URL function emphasized with a red square.](/images/speakeasy/copy-combined-spec-url.png) + -## Manual Set Up +### Update your `docs.json` configuration file -Alternatively, you can manually set up the following files in your Mintlify docs repo. +Add the combined spec URL to an **Anchors** or **Tabs** section in your `docs.json` file. +Add the combined spec URL to an anchor by updating the `anchor` field in your `docs.json` file as follows: -```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 docs.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 a tab by updating the `tab` field in the `docs.json` file as follows: + +```json docs.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 your API docs and interacted with in the playground.