posit-dev / posit-dev/quarto-openapi

Add schema/example toggle for request and response bodies

Open
#17 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
3
Forks
1
Avg merge
11d 5h
Merged PRs (30d)
3

Description

Problem

When rendering request and response bodies, the extension currently shows only the schema property table (field names, types, descriptions). There is no way to see a generated JSON example of what the request or response actually looks like.

Tools like RapiDoc and Swagger UI provide a "Model / Example" toggle that lets users switch between the structured schema view and a concrete JSON example assembled from field-level example values. This is valuable because:

  • Schema tables are good for understanding individual fields, constraints, and descriptions
  • JSON examples are good for quickly grasping the overall shape and copy-pasting into code

Proposal

For each request body and response body that has a schema, render both views using a Quarto tabset:

::: {.panel-tabset}
## Schema

+----------+----------+---------------------------------------------+
| Name     | Type     | Description                                 |
+==========+==========+=============================================+
| `name`   | `string` | The name for this API key.                  |
+----------+----------+---------------------------------------------+
| `status` | `string` | The current status. Enum: `active`, `locked` |
+----------+----------+---------------------------------------------+

## Example

```json
{
  "name": "Automation",
  "status": "active"
}
```
:::
Example generation

The JSON example should be assembled from example values on individual schema properties, following OpenAPI conventions:

  1. If the schema itself has an example field, use it directly
  2. Otherwise, build an object from each property's example value
  3. For properties without example, use a sensible placeholder based on type ("" for string, 0 for integer, false for boolean, etc.)
  4. Respect readOnly / writeOnly — request body examples should exclude readOnly fields, response examples should exclude writeOnly fields
  5. Handle nested objects and arrays recursively
When to show the toggle
  • Show both tabs when the schema has properties with example values (most cases)
  • Show schema only when there are no examples to assemble (degenerate case — avoids showing a useless placeholder-only example)
  • The default visible tab should be configurable (e.g., default-schema-tab: model or example in _quarto.yml)
Scope

This applies to:

  • Response body schemas (in the Responses section)
  • Request body schemas (in the Request body section)
  • Potentially top-level schema component definitions if those are rendered separately

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the TypeScript rendering path for request and response body schemas in the Quarto OpenAPI extension. Compare the existing schema-table output with the proposed Quarto panel-tabset, then define completion as recursive examples, readOnly/writeOnly filtering, configurable default tabs, and schema-only output when no examples exist.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.