Skip to content

Commit 8076b06

Browse files
simplesagarsimplesagar
committed
chore: update images
1 parent a3613c0 commit 8076b06

File tree

1 file changed

+57
-70
lines changed

1 file changed

+57
-70
lines changed

‎integrations/sdks/speakeasy.mdx‎

Lines changed: 57 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -3,95 +3,82 @@ title: Speakeasy
33
description: Automate your SDK usage snippets in the API playground
44
---
55

6-
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.
6+
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.
77

8-
## Speakeasy SDK Repository Changes
8+
<Screenshot url="docs.myapi.com" docs={true}>
9+
![Speakeasy code snippets with
10+
Mintlify.](./mintlify-with-speakeasy-openapi.png)
11+
</Screenshot>
912

10-
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.
13+
## Prerequisites
1114

12-
```yaml .speakeasy/workflow.yaml
13-
targets:
14-
my-target:
15-
target: typescript
16-
source: my-source
17-
codeSamples:
18-
output: codeSamples.yaml
19-
```
15+
To integrate Mintlify with Speakeasy, you'll need the following:
2016

21-
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.
17+
- A [Mintlify documentation repository](https://mintlify.com/docs/quickstart#creating-the-repository).
18+
- A Speakeasy-generated SDK with a configured [automated code sample URL](https://www.speakeasy.com/docs/code-samples/automated-code-sample-urls).
2219

23-
## Mintlify Docs Repository Changes
20+
## Setting up the integration
2421

25-
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.
22+
### Get the API's combined spec public URL from the registry
2623

27-
### Interactive CLI Set Up
24+
Navigate to the [Speakeasy Dashboard](https://app.speakeasy.com) and open the **API Registry** tab. Open the `*-with-code-samples` entry for the API.
2825

29-
Run the following commands to set up the `.speakeasy/workflow.yaml` and `.github/workflows/sdk_generation.yaml` files through the interactive Speakeasy CLI.
26+
<Screenshot darkened docs={true}>
27+
![Screenshot showing the Speakeasy API
28+
Registry page](./openapi-registry-and-combined-spec.png)
29+
</Screenshot>
3030

31-
```bash
32-
speakeasy configure sources
33-
speakeasy configure github
34-
```
31+
> NOTE: If the entry is not labeled **Combined Spec**, ensure that the API
32+
> has an [automatic code sample
33+
> URL](https://www.speakeasy.com/docs/code-samples/automated-code-sample-urls) configured.
3534
36-
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.
35+
From the registry entry's page, copy the provided public URL.
3736

38-
![](/images/speakeasy-1.webp)
37+
<Screenshot darkened docs={true}>
38+
![Screenshot showing the combined spec registry
39+
entry with the copy URL function highlighted](./copy-combined-spec-url.png)
40+
</Screenshot>
3941

40-
Add the overlay created by Speakeasy to inject code snippets into your spec.
4142

42-
![](/images/speakeasy-2.webp)
43+
### Update the `mint.json` configuration file
4344

44-
Provide a name and path for the OpenAPI spec. This will be the final spec used by Mintlify.
45+
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.
4546

46-
![](/images/speakeasy-3.webp)
47+
Add the combined spec URL to **Anchors** by updating the `anchor` field in the `mint.json` file as follows:
4748

48-
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.
49+
```json mint.json
50+
{
51+
"anchors": [
52+
{
53+
"name": "API Reference",
54+
// !mark
55+
"openapi": "SPEAKEASY_COMBINED_SPEC_URL",
56+
"url": "api-reference",
57+
"icon": "square-terminal"
58+
}
59+
]
60+
}
61+
```
4962

50-
## Manual Set Up
63+
Add the combined spec URL to **Tabs** by updating the `tab` field in the `mint.json` file as follows:
64+
65+
```json mint.json
66+
{
67+
"tabs": [
68+
{
69+
"name": "API Reference",
70+
"url": "api-reference",
71+
// !mark
72+
"openapi": "SPEAKEASY_COMBINED_SPEC_URL"
73+
}
74+
]
75+
}
76+
```
5177

52-
Alternatively, you can manually set up the following files in your Mintlify docs repo.
78+
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.
5379

80+
## Next steps
5481

55-
```yaml .speakeasy/workflow.yaml
56-
workflowVersion: 1.0.0
57-
sources:
58-
docs-source:
59-
inputs:
60-
- location: {{your_api_spec}} # local or remote references supported
61-
overlays:
62-
- location: https://raw.githubusercontent.com/{{your_sdk_repo_1}}/codeSamples.yaml
63-
- location: https://raw.githubusercontent.com/{{your_sdk_repo_2}}/codeSamples.yaml
64-
- location: https://raw.githubusercontent.com/{{your_sdk_repo_3}}/codeSamples.yaml
65-
output: openapi.yaml
66-
targets: {}
67-
```
82+
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).
6883

69-
```yaml .speakeasy/workflows/sdk_generation.yaml
70-
name: Generate
71-
permissions:
72-
checks: write
73-
contents: write
74-
pull-requests: write
75-
statuses: write
76-
"on":
77-
workflow_dispatch:
78-
inputs:
79-
force:
80-
description: Force generation of SDKs
81-
type: boolean
82-
default: false
83-
schedule:
84-
- cron: 0 0 * * *
85-
jobs:
86-
generate:
87-
uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15
88-
with:
89-
force: ${{ github.event.inputs.force }}
90-
mode: pr
91-
speakeasy_version: latest
92-
secrets:
93-
github_access_token: ${{ secrets.GITHUB_TOKEN }}
94-
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
95-
```
9684

97-
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.

0 commit comments

Comments
 (0)