posit-dev / posit-dev/quarto-openapi
Add schema/example toggle for request and response bodies
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:
- If the schema itself has an
examplefield, use it directly - Otherwise, build an object from each property's
examplevalue - For properties without
example, use a sensible placeholder based on type (""for string,0for integer,falsefor boolean, etc.) - Respect
readOnly/writeOnly— request body examples should excludereadOnlyfields, response examples should excludewriteOnlyfields - Handle nested objects and arrays recursively
When to show the toggle
- Show both tabs when the schema has properties with
examplevalues (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: modelorexamplein_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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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