Automated code sample URLs

For paid accounts, Speakeasy can automatically apply code samples to your base OpenAPI document in the cloud, with no intervention required. This is the most elegant solution for exposing code samples to documentation providers.

In the APIs tab of the dashboard, look for an entry marked as Combined Spec. Click into the entry to see a breakdown of the base OpenAPI document and code samples overlays that were used to produce it.

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 your base OpenAPI document and code samples when you generate an SDK using GitHub Actions and merge the changes 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 you have not yet completed your SDK setup in GitHub, you may see a notification like the following in the Docs tab.

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

• Each SDK’s workflow.yaml file must include the following:
  • The source (your OpenAPI document) with a specified registry location.
  • The target (your 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 your setup is correct, the following will be available in the APIs tab of the Speakeasy dashboard:

• An entry for your 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 you are not ready to set up publishing, you can temporarily set up the following tagging action in each of your SDK repos.

.github/workflows/tagging.yaml

name: Speakeasy Tagging
permissions:
  checks: write
  contents: write
  pull-requests: write
  statuses: write
"on":
  push:
    branches:
      - main
    paths: []
  workflow_dispatch: {}
jobs:
  tag:
    uses: speakeasy-api/sdk-generation-action/.github/workflows/tag.yaml@v15
    with:
      registry_tags: main
    secrets:
      github_access_token: ${{ secrets.GITHUB_TOKEN }}
      speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}