Integrate Speakeasy with ReadMe
Autogenerated code snippets from Speakeasy SDKs can be integrated directly into a ReadMe documentation site.
Prerequisites
To integrate ReadMe with Speakeasy, you’ll need the following:
- A ReadMe project created (opens in a new tab).
- A Speakeasy-generated SDK with a configured automated code sample URL.
Setting up the integration
Configure workflow.yaml
for ReadMe
To display code samples from Speakeasy SDKs in ReadMe, update the workflow.yaml
file to support their proprietary OpenAPI extension.
In the SDK target configuration, set the codeSamples.style
field to readme
:
targets:my-target:target: typescriptcodeSamples:style: readmelangOverride: javascript # see note belowregistry:location: registry.speakeasyapi.dev/...blocking: false...
Note for TypeScript
If the target
value is set to typescript
, the langOverride
field must be
set to javascript
or generated code samples will not be displayed in
ReadMe.
If target
is not set to typescript
, then langOverride
should be set to
auto-detect
.
Get the API’s combined spec public URL from the registry
Navigate to the Speakeasy Dashboard (opens in a new tab) and open the API Registry tab. Open the *-with-code-samples
entry for the API.
NOTE: If the entry is not labeled Combined Spec, ensure that the API has an automatic code sample URL configured.
From the registry entry’s page, copy the provided public URL.
Get the API’s combined spec public URL from the registry
In the ReadMe dashboard (opens in a new tab), open your project.
Click the API Reference tab, then click + New API Definition.
Paste the combined spec URL from Speakeasy into the text input below Import from URL, then click Import.
Speakeasy-generated code snippets are now available in the ReadMe project’s API Reference section.
Upload the combined spec URL to ReadMe
For help customizing ReadMe API references generated from OpenAPI documents, see the ReadMe OpenAPI support documentation (opens in a new tab).