Code Samples

printing press supports the x-codeSamples OpenAPI extension on operations.

When an operation needs real, authored code examples instead of generated curl alone.

The samples are rendered as a dedicated Code Samples section on the operation page, they are also included in the generated markdown and agentic documentation output.

Basic format

Add x-codeSamples to an operation. Each entry can be an object with a language, label, and source block.

paths:
  /bookings:
    post:
      operationId: create-booking
      summary: Create a booking
      x-codeSamples:
        - lang: typescript
          label: create-booking_json
          source: |
            import { TrainTravelSDK } from "train-travel-sdk";

            const trainTravel = new TrainTravelSDK({
              oauth2: process.env.TRAINTRAVELSDK_O_AUTH2 ?? "",
            });

            const booking = await trainTravel.bookings.createJson({
              tripId: "4f4e4e1c-c824-4d63-b37a-d8d698862f1d",
              passengerName: "John Doe",
            });

            console.log(booking.id);            
      responses:
        "201":
          description: Booking successful

source must be a string block, or a local $ref object. Empty samples are skipped with a warning.

Object fields

lang and label are optional. source is required.

Tabs and labels

When an operation has more than one code sample, printing press renders them as tabs.

The tab label is chosen in this order:

• lang
• label
• Sample N

If label is present and is different from lang, it is also shown above the code block as the sample name. That makes labels like create-booking_raw, create-booking_python, or create-booking_go stand out without making the tab bar too noisy.

x-codeSamples:
  - lang: typescript a
    label: create-booking_json
    source: |
      await sdk.bookings.createJson({ tripId: "abc" });      
  - lang: typescript b
    label: create-booking_raw
    source: |
      await sdk.bookings.createRaw({
        body: JSON.stringify({ tripId: "abc" }),
      });      
  - lang: go
    label: create-booking_go
    source: |
      client.Bookings.Create(ctx, booking)      

This renders tabs named ‘TYPESCRIPT A’, ‘TYPESCRIPT B’, and ‘GO’, with the specific sample labels shown above each code block.

Plain code blocks

Some specs do not use the object format. They just list blocks of code.

That works too:

x-codeSamples:
  - |
    const response = await fetch("https://api.example.com/bookings", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.TRAIN_TRAVEL_TOKEN}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        trip_id: "4f4e4e1c-c824-4d63-b37a-d8d698862f1d",
        passenger_name: "John Doe"
      })
    });

    console.log(await response.json());    
  - |
    import requests

    response = requests.post(
        "https://api.example.com/bookings",
        headers={"Authorization": "Bearer TRAIN_TRAVEL_TOKEN"},
        json={"trip_id": "4f4e4e1c-c824-4d63-b37a-d8d698862f1d"},
    )

    print(response.json())    

Because plain entries do not have lang or label, the rendered tabs are named ‘SAMPLE 1’, ‘SAMPLE 2’`, and so on.

Use the correct Code Samples object when you want control over tabs and labels, or just blobs of code if you don’t care.

External files

For larger examples, keep the code in real source files and reference them from the OpenAPI document.

openapi.yaml
snippets/
  create-booking-json.ts
  create-booking.go
  create-booking.py

Reference those files with source.$ref.

(Just like you would normally)

paths:
  /bookings:
    post:
      operationId: create-booking
      x-codeSamples:
        - lang: typescript
          label: create-booking_json
          source:
            $ref: snippets/create-booking-json.ts
        - lang: go
          label: create-booking_go
          source:
            $ref: snippets/create-booking.go
        - lang: python
          label: create-booking_python
          source:
            $ref: snippets/create-booking.py

Local refs are resolved relative to the operation source file when the OpenAPI document is split across files. Otherwise they are resolved relative to the root/entry document file.

Colocated path files can keep snippets next to the operations, cleanly.

openapi.yaml
paths/
  bookings.yaml
  snippets/
    create-booking.go

# paths/bookings.yaml
post:
  operationId: create-booking
  x-codeSamples:
    - lang: go
      source:
        $ref: snippets/create-booking.go

Reference safety

Code sample refs are intentionally local and bounded.

printing press will warn and skip a referenced sample when the ref is:

• remote
• missing
• empty
• a directory or not a regular file
• resolves outside the spec root
• is larger than 1MiB

The build continues. Bad samples should not take down the documentation printing run.

Syntax highlighting

Code samples are highlighted during HTML generation using server-side syntax highlighting.

When lang is set, it is used as the highlighting language. When lang is missing, printing press lets the highlighter inspect the source. If no language can be detected, the source is still rendered safely as escaped plain text.

The UI does not re-highlight samples in the browser. The generated HTML already contains the highlighted code.

Where samples appear

Code samples are emitted in every documentation surface where they are useful:

• the operation HTML page, in a dedicated Code Samples section
• per-operation markdown
• LLM and agent output
• JSON artifacts, as structured codeSamples data

They are operation-scoped. Add them to the operation that owns the example.