update content

Author: ethanpalm

integrations/sdks/speakeasy.mdx

@@ -1,97 +1,70 @@
 ---
-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.
+<Note>
+  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.
+</Note>
 
-![](/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.