Nest Request Body fields under their heading in OpenAPI docs#19009
Nest Request Body fields under their heading in OpenAPI docs#19009djgrove wants to merge 3 commits into
Conversation
Wrap each operation's Request Body subtree in a bordered card (`.api-request-body`) so its fields are visually nested under the Request Body heading, matching how the Responses section already renders its status-coded `.api-response` cards. Without this, the body's schema fields sat flush-left at the same margin as the section's Request Parameters list, making nested fields look like peer parameters. Request Parameters keep their existing flat layout — they're path and query inputs, not fields of an enclosing object, so indentation would imply false nesting.
Docs review — PR #19009Focused, low-risk change: a bordered A few small notes — all minor / optional: CSS — duplication and placement
If you'd rather keep them separate to allow them to diverge later, then at least consider placing the new Visual asymmetry between the two card branchesIn Pre-existing nit (not blocking, not yours to fix here)
Things I checked and that look fine
Mention me (@claude) if you'd like another pass after applying changes, or if you'd prefer me to focus on a specific part of the review. |
|
Your site preview for commit cd22b71 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-19009-cd22b711.s3-website.us-west-2.amazonaws.com |
Lighthouse Performance ReportCommit: cd22b71 | Metric definitions
|
There was a problem hiding this comment.
Pull request overview
This PR improves the generated OpenAPI endpoint documentation layout by visually nesting request body fields under the Request Body heading, matching the existing “card” presentation used for response schemas.
Changes:
- Wrap request body schema label + property list in a new
.api-request-bodycontainer in the endpoint template. - Add
.api-request-bodyCSS to present request bodies as bordered/padded cards with cleaned-up list borders/padding.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| layouts/partials/openapi/endpoint.html | Wrapes the request body schema/fields in .api-request-body for both $ref and inline schema branches. |
| assets/fingerprinted/css/openapi.css | Introduces .api-request-body styling to mirror response cards and adjust nested .api-params list presentation. |
These cards are intentionally identical visually — the only reason .api-request-body exists is to wrap the Request Body's schema list the same way .api-response wraps each response. Sharing selectors removes the 5 duplicated rules and keeps the two in lockstep if either is ever restyled. Also fixes source order: the descendant selector .api-request-body .api-schema-label no longer appears before the base .api-schema-label rule that defines it.
|
Thanks @claude — went through each section: CSS consolidation. Agreed and applied your suggested merge: 9418ca5. The two cards are meant to be identical and now share selectors; this also fixes the source-order issue you flagged (the descendant selector for Inline-schema branch asymmetry. Holding the current behavior. Pre-existing Brace balance / palette / a11y observations. Confirmed. |
|
Claude finished @djgrove's task in 1m 15s —— View job Follow-up review — all three resolutions look goodVerified each point against the current branch. CSS consolidation (9418ca5). Diff is clean: 5 duplicated rules collapsed to combined selectors, Inline-schema branch — agreed, current behavior is correct. I went back and read
The Copilot reviewer's two notes also land in the same places — CSS dedup is now addressed by 9418ca5, and their suggestion about reusing No further changes from me — looks ready.
|
Collapses the parallel $ref / inline branches in the Request Body template into a single call to openapi/response-schema.html — the same partial Responses use to render their schema card. Drops ~30 lines of duplicated resolve/label/property-list logic from endpoint.html and ensures request and response schemas can't drift as response-schema.html evolves. Incidentally fixes the pre-existing $resolved.required vs ($resolved.required | default slice) asymmetry between the two branches; property-rows.html already defaults nil required slices to an empty slice internally.
Summary
.api-request-body) that mirrors how.api-responsealready presents response schemas, so body fields are visually nested under the Request Body heading instead of sitting flush-left with the section's Request Parameters list.Problem
On generated OpenAPI docs pages (
/docs/reference/cloud-rest-api/...), each operation shows three field sections under the endpoint heading: Request Parameters, Request Body, and Responses. All three render fields via the sameproperty-rows.htmlpartial. The inconsistency was structural, not in the list rendering:<div class=\"api-response\">, a bordered, padded card. The schema label and field list live inside, so every response field reads as nested under the Responses heading.<h4>Request Body</h4>was followed directly by the schema label and<ul class=\"api-params\">, all flush-left — at the same margin as the path/query parameters listed above.Net effect: a body field like
entitylooked like just another peer parameter rather than a member of, say,CreateXRequest. Internal feedback flagged exactly this confusion.Change
layouts/partials/openapi/endpoint.html: wrap the request body's schema label and property list in<div class=\"api-request-body\">for both the$refand inline-schema branches.assets/fingerprinted/css/openapi.css: add.api-request-bodystyles (same border/padding/radius/background as.api-response) plus the matching.api-paramsfirst/last-child overrides so the field list reads cleanly inside the card.Test plan
/docs/reference/cloud-rest-api/) the Request Body section now renders as a bordered card, visually nesting its schema fields under the Request Body heading.$ref) schema and one that uses$refto a component schema to verify both branches.