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: typescript
    codeSamples:
      style: readme
      langOverride: javascript # see note below
      registry:
        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).