SDK code samples in OpenAPI

If users call your API through an SDK instead of raw HTTP, add samples with the OpenAPI extension x-codeSamples. Holocron shows them as extra tabs in the Request example panel next to the generated cURL snippet.

This is the same extension Mintlify, Stainless, Speakeasy, and hey-api use.

Where samples appear

On each generated endpoint page, the right aside Request example panel lists tabs in this order:

cURL (always generated)
Each x-codeSamples entry (your SDK snippets)
Named request body examples from the spec (JSON payloads)

  OpenAPI operation
        │
        v
  ┌─────────────────────────────────────────┐
  │ Request example                         │
  │  cURL  │  TypeScript  │  Python  │  …   │
  │  ┌───────────────────────────────────┐  │
  │  │  await client.users.list()        │  │
  │  └───────────────────────────────────┘  │
  └─────────────────────────────────────────┘

SDK tabs are copy-only. Live try-it still uses HTTP.

Language tabs sync by title across Request example panels (and other <Tabs sync> groups). Pick TypeScript once and the next endpoint opens on TypeScript when that tab exists.

Hand-written samples

Add x-codeSamples on any path method:

123456789101112131415161718192021paths:
  /users:
    get:
      summary: List users
      x-codeSamples:
        - lang: TypeScript
          label: TypeScript
          source: |
            import { Acme } from '@acme/sdk'
            const client = new Acme()
            await client.users.list({ role: 'editor' })
        - lang: Python
          label: Python
          source: |
            from acme import Acme
            client = Acme()
            client.users.list(role="editor")
        - lang: bash
          label: CLI
          source: |
            acme users list --role editor

Field	Required	Description
`lang`	yes	Language id for highlighting (`TypeScript`, `python`, `bash`, …)
`source`	yes	Inline snippet body (string). Use a string, not a `$ref`; external refs are not resolved for samples.
`label`	no	Tab title. Defaults to `lang`.

Multiple samples can share a language with different labels (for example two TypeScript flows).

Keep label short. The Request example tab bar is narrow; long labels force horizontal scroll.

Stainless and Speakeasy

Point Holocron at a decorated OpenAPI file (or URL once remote specs are supported) that already includes x-codeSamples.

Stainless: set openapi.code_samples: 'mintlify' in stainless.yml, publish the OpenAPI URL from the Release tab, and set that file or path as your tab openapi value.

Speakeasy: use the registry combined spec entry (*-with-code-samples) and point openapi at that document.

No Holocron-specific config beyond loading the decorated spec.

Generate samples with hey-api

hey-api (@hey-api/openapi-ts) can generate a typed SDK and write x-codeSamples back into a source OpenAPI JSON. Point Holocron at that decorated file.

1. Install

1npm install -D @hey-api/openapi-ts

2. Config

12345678910111213141516171819202122232425// openapi-ts.config.ts
import { defineConfig } from '@hey-api/openapi-ts'

export default defineConfig({
  input: './openapi.yaml',
  output: {
    path: './src/client',
    // Writes a decorated copy of the input spec after intents run.
    // Path is resolved as path.resolve(output.path, source.path, fileName + '.json')
    source: {
      path: '../..', // project root when output is ./src/client
      fileName: 'openapi.with-samples',
    },
  },
  plugins: [
    '@hey-api/client-fetch',
    {
      name: '@hey-api/sdk',
      // Generate TypeScript usage snippets and attach them via x-codeSamples
      examples: {
        language: 'TypeScript',
      },
    },
  ],
})

output.source writes the input document after intents run. The SDK plugin’s examples option appends each generated snippet to that operation’s x-codeSamples.

The file lands at path.resolve(output.path, source.path, fileName + '.json'). With the config above that is openapi.with-samples.json at the project root. If source.path is '..' instead, the file would be src/openapi.with-samples.json.

3. Script

123456// package.json
{
  "scripts": {
    "openapi:sdk": "openapi-ts"
  }
}

1npm run openapi:sdk

4. Point Holocron at the decorated file

1234{
  "tab": "API Reference",
  "openapi": "openapi.with-samples.json"
}

Regenerate the decorated file in CI whenever the base OpenAPI or SDK config changes, then build docs.

  openapi.yaml ──> openapi-ts (sdk.examples) ──> openapi.with-samples.json
                                                         │
                                                         v
                                              docs.json openapi field
                                                         │
                                                         v
                                              Request example tabs

You can also hand-edit x-codeSamples on a few important endpoints and leave the rest as cURL only. Mixed specs work fine.

Example in this monorepo

The Holocron example site ships example/api.yaml with x-codeSamples on List users and Create user. Open the API Reference tab locally and switch the Request example tabs between cURL and the SDK languages.