diff --git a/integrations/sdks/copy-combined-spec-url.png b/integrations/sdks/copy-combined-spec-url.png new file mode 100644 index 000000000..4efae51d0 Binary files /dev/null and b/integrations/sdks/copy-combined-spec-url.png differ diff --git a/integrations/sdks/mintlify-with-speakeasy-openapi.png b/integrations/sdks/mintlify-with-speakeasy-openapi.png new file mode 100644 index 000000000..c11eed939 Binary files /dev/null and b/integrations/sdks/mintlify-with-speakeasy-openapi.png differ diff --git a/integrations/sdks/openapi-registry-and-combined-spec.png b/integrations/sdks/openapi-registry-and-combined-spec.png new file mode 100644 index 000000000..710148ded Binary files /dev/null and b/integrations/sdks/openapi-registry-and-combined-spec.png differ diff --git a/integrations/sdks/speakeasy.mdx b/integrations/sdks/speakeasy.mdx index d45628bed..c8eff6278 100644 --- a/integrations/sdks/speakeasy.mdx +++ b/integrations/sdks/speakeasy.mdx @@ -3,95 +3,71 @@ 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.](./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. +To integrate Mintlify with Speakeasy, you'll need the following: -## Mintlify Docs Repository Changes + - A [Mintlify documentation repository](https://mintlify.com/docs/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). -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. +## Setting up the integration -### Interactive CLI Set Up +### Get the API's combined spec public URL from the registry -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 -``` +Navigate to the [Speakeasy Dashboard](https://app.speakeasy.com) and open the **API Registry** tab. Open the `*-with-code-samples` entry for the API. -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. +![Screenshot showing the Speakeasy API Registry page](./openapi-registry-and-combined-spec.png) -![](/images/speakeasy-1.webp) +> 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. -Add the overlay created by Speakeasy to inject code snippets into your spec. +From the registry entry's page, copy the provided public URL. -![](/images/speakeasy-2.webp) +![Screenshot showing the combined spec registry entry with the copy URL function highlighted](./copy-combined-spec-url.png) -Provide a name and path for the OpenAPI spec. This will be the final spec used by Mintlify. +### Update the `mint.json` configuration file -![](/images/speakeasy-3.webp) +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. -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. +Add the combined spec URL to **Anchors** by updating the `anchor` field in the `mint.json` file as follows: -## Manual Set Up +```json mint.json +{ + "anchors": [ + { + "name": "API Reference", + // !mark + "openapi": "SPEAKEASY_COMBINED_SPEC_URL", + "url": "api-reference", + "icon": "square-terminal" + } + ] +} +``` -Alternatively, you can manually set up the following files in your Mintlify docs repo. +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" + } + ] +} +``` +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. -```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: {} -``` +## Next steps -```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 }} -``` +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). -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.