Integrate Speakeasy With ReadMe

Overview

Auto-generated code snippets from Speakeasy SDKs can be integrated directly into a ReadMe documentation site.

Setting up the Integration

Prerequisites

IMPORTANT

Before continuing with this guide, ensure that the following prerequisites have been met:

• An Automated Code Sample URL has been configured for the desired Speakeasy SDK, and
• A ReadMe project has been created.

Once those requirements have been met, proceed with the following steps.

Configure workflow.yaml for ReadMe

To display code samples generated by Speakeasy SDKs in ReadMe, you must update the workflow.yaml configuration file to support their proprietary OpenAPI extension.

Simply change the codeSamples.style field for your desired target in the workflow.yaml file 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 else generated code samples will not be displayed in ReadMe.

If target is not set to typescript, then langOverride should be set to auto-detect.

Locate & Copy the Combined Spec URL

First, navigate to the Speakeasy Dashboard (opens in a new tab) and open the API Registry tab. Once there, open the *-with-code-samples entry for the desired API.

NOTE: If this entry is not labeled with Combined Spec, ensure that the API has an Automatic Code Sample URL configured.

From the registry entry’s page, copy the provided public URL.

Upload the Combined Spec URL to ReadMe

Next, from the ReadMe dashboard (opens in a new tab), open a project.

Click on the API Reference tab, then click + New API Definition.

In the form that appears, paste the copied URL into the text input below Import from URL, then click Import.

What Next?

After completing these steps, Speakeasy-generated code snippets are viewable in the ReadMe project’s API Reference section. For guidance on customizing ReadMe API References generated from OpenAPI specifications, refer to the ReadMe OpenAPI Support Documentation (opens in a new tab).