Speakeasy Logo
Skip to Content
DocumentationSDK DocumentationCode SamplesAutomated Code Sample URLs

Automated code sample URLs

Get the API’s combined spec public URL from the registry

Navigate to the Speakeasy Dashboard  and open the API Registry overview. Select the relevant API and open the entry labeled with type Combined Spec. This is typically at the bottom under “Related Documents”.

app.speakeasy.com
Screenshot showing the Speakeasy API Registry page

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 using the “Share” button on the top right.

app.speakeasy.com
Screenshot showing the combined spec registry entry with the share function highlighted.

To configure one of these combined code sample specs as a public URL for documentation providers, visit the Docs tab in the Speakeasy dashboard.

How Speakeasy automates code sample URLs

Speakeasy automatically tracks the base OpenAPI document and code samples when an SDK is generated using GitHub Actions and changes are merged to the main branch. Based on this, Speakeasy generates a combined spec in the background that contains all your existing OpenAPI operations along with any added x-code-samples extensions.

Requirements for using automated code sample URLs

If the SDK setup in GitHub is not yet complete, a notification like the following may appear in the Docs tab.

app.speakeasy.com
Automatic code sample URLs not available.

To use automated code sample URLs, the SDK must meet the following requirements:

  • Each SDK’s workflow.yaml file must include the following:
    • The source (the OpenAPI document) with a specified registry location.
    • The target (the SDK) with a codeSamples section that includes a specified registry location.
  • The SDK must be generated with GitHub Actions and merged to main.
  • The SDK GitHub Action must be in direct mode, or the sdk-publish action must be configured. While publishing to a package manager is not necessary, release tagging must be handled by this action.
  • The base OpenAPI document must not include x-codeSamples extensions, as they will not be overwritten.

When the setup is correct, the following will be available in the APIs tab of the Speakeasy dashboard:

  • An entry for the base OpenAPI document (for example, my-source).
  • For each SDK you include, a corresponding code samples overlay (for example, my-source-{lang}-code-samples).

Revisions to the base OpenAPI document and code sample overlays must be tagged with main, which is why using GitHub Actions is required.

Alternatives to configuring sdk-publish.yaml:

If publishing setup is not ready, temporarily set up the following tagging action in each SDK repo.

Last updated on