Automated Code Sample URLs

For paid accounts, Speakeasy can automatically apply code samples to your base spec 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. When clicking into it, you will see a breakdown of the base spec and code samples overlays that were used to produce it.

You can easily configure one of these combined code sample specs as a public URL for documentation providers by visiting the Docs tab in the speakeasy dashboard.

How it Works

Speakeasy automatically tracks your base OpenAPI spec and code sample documents when you generate your SDK with Github Actions and merge the result to main. From this we will compute a combined spec in the background that contains all of your existing openapi operations as well as any x-code-samples extensions that were added.

Product Requirements

If you have not yet completed your SDK setup in Github you may see an image like the following in the Docs tab.

Speakeasy has the following requirements for an SDK to be able to use automated code sample URLs:

• In your workflow.yaml for each SDK you should have the following included:
  • The source (your OpenAPI document) must have a registry location specified.
  • The target (your SDK) must have a codeSamples section with a registry location specified.
• Your SDK must be generated with GitHub Actions and merged to main.
• Your SDK GitHub Action must either by in direct mode or you should have the sdk-publish action configured. It is not necessary to actually publish your SDK to a package manager. But it is necesarry that release tagging is being completed by this action.
• Your base openapi spec must not already have x-codeSamples extensions since we will not overwrite them.

When everything is setup correctly you should see the following you should see the following in the APIs tab of the Speakeasy dashboard:

• An entry for your base OpenAPI document (e.g. my-source)
• A code samples overlay (e.g. my-source-{lang}-code-samples) for each SDK you want is in your final document
• Each of these must have a main tag on any revision (this is why GitHub Actions is required)

Alternative options to sdk-publish.yaml:

If you are really not ready to setup publishing, you can temporarily setup 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 }}