Support templated code samples for API endpoints

Problem

The Quarto OpenAPI extension renders endpoint documentation (descriptions, parameters, request/response schemas) but does not generate code samples. Auto-generated code samples in multiple languages (curl, Python, R) are a key part of the API reference developer experience.

Proposal

Add templated code sample generation, rendered as a Quarto tabset per endpoint. The extension should:

1. Define language templates that can be customized per-project via configuration in _quarto.yml under the openapi key
2. Auto-generate samples for each endpoint using the operation's method, path, parameters, and request body schema examples
3. Support custom overrides via the OpenAPI x-code-samples extension — when present, use those instead of the template
4. Render as a Quarto tabset (::: {.panel-tabset}) so users can switch between languages

Configuration sketch

# _quarto.yml
openapi:
  spec: "api/openapi.json"
  output: "api/reference.qmd"
  code-samples:
    base-url: "https://api.example.com"
    path-examples:
      guid: "25438b83-ea6d-4839-ae8e-53c52ac5f9ce"
      id: "101"
    languages:
      - label: curl
        lang: bash
        template: templates/curl.jinja
      - label: Python
        lang: python
        template: templates/python.jinja
      - label: R
        lang: r
        template: templates/r.jinja

Template variables

Templates would receive these variables for rendering:

• method — HTTP method (GET, POST, etc.)
• path — endpoint path with example values substituted for path parameters
• raw_path — endpoint path with {param} placeholders intact
• query — formatted query string from required parameters with example values
• data — request body example assembled from schema field-level examples (null if none)
• base_url — from configuration

Example templates

curl:

curl --silent --show-error -L --max-redirs 0 --fail \
    -X {{ method | upper }} \
    -H "Authorization: Key ${API_KEY}" \
    {% if data %}--data-raw '{{ data | tojson }}' \{% endif %}
    "{{ base_url }}{{ path }}{{ query }}"

Python:

import httpx

API_KEY = "your-api-key"
{% if data %}data = {{ data }}{% endif %}
response = httpx.{{ method | lower }}(
    "{{ base_url }}{{ path }}",
    headers={"Authorization": f"Key {API_KEY}"},
    {% if data %}json=data,{% endif %}
)

Rendering output

Each endpoint section would include a tabset:

::: {.panel-tabset}
## curl
```bash
curl --silent --show-error -L --max-redirs 0 --fail \
    -X GET \
    -H "Authorization: Key ${API_KEY}" \
    "https://api.example.com/v1/users/25438b83-.../keys/101"
```

## Python
```python
import httpx
response = httpx.get(
    "https://api.example.com/v1/users/25438b83-.../keys/101",
    headers={"Authorization": f"Key {API_KEY}"},
)
```
:::

Behavior details

• Auto-generate samples for every endpoint unless x-code-samples is present on the operation (custom samples override the template)
• Substitute path parameters with example values from configuration (path-examples map)
• Include request body examples assembled from schema field-level example values
• Include required query parameters with example values
• When code-samples is not configured in _quarto.yml, no samples are generated (opt-in)

Alternatives considered

• Embedding samples in OpenAPI descriptions: Doesn't scale — every endpoint would need manually written samples in three languages.
• Using x-code-samples on every operation: Works but is verbose and doesn't leverage the repetitive structure of code samples.
• Client-side generation (like RapiDoc): Not compatible with static Quarto rendering.

Start by reviewing the existing endpoint rendering flow and the proposed code-samples configuration in _quarto.yml. Trace how OpenAPI operations expose parameters, request bodies, and x-code-samples, then define the rendering boundaries for templates and Quarto tabsets. Done means configured projects render language tabs for each endpoint, custom samples override generated ones, and unconfigured projects remain unchanged.