Nest Request Body fields under their heading in OpenAPI docs

assets/fingerprinted/css/openapi.css

@@ -337,9 +337,11 @@
     font-size: 0.9rem;
 }
 
-/* Response blocks: one per inline-rendered status (2xx, or 4xx/5xx with a
-   schema). Stock errors collapse into .api-response-errors below. */
+/* Bordered card used for the Request Body and each Response. Both nest a
+   field list (.api-params) under a section heading; sharing the selector
+   keeps them visually in lockstep. */
 
+.api-request-body,
 .api-response {
     margin: 1rem 0 1.25rem;
     padding: 0.75rem 1rem;
@@ -348,6 +350,23 @@
     background: #fff;
 }
 
+.api-request-body .api-params,
+.api-response .api-params {
+    margin-top: 0.5rem;
+    border-top: none;
+}
+
+.api-request-body .api-param:first-child,
+.api-response .api-param:first-child {
+    padding-top: 0;
+}
+
+.api-request-body .api-param:last-child,
+.api-response .api-param:last-child {
+    border-bottom: none;
+    padding-bottom: 0;
+}
+
 .api-response-header {
     display: flex;
     align-items: baseline;
@@ -380,18 +399,8 @@
     color: #5b3fa3;
 }
 
-.api-response .api-params {
-    margin-top: 0.5rem;
-    border-top: none;
-}
-
-.api-response .api-param:first-child {
-    padding-top: 0;
-}
-
-.api-response .api-param:last-child {
-    border-bottom: none;
-    padding-bottom: 0;
+.api-request-body .api-schema-label {
+    margin-top: 0;
 }
 
 /* Status chip: compact pill showing HTTP status code with semantic color. */

layouts/partials/openapi/endpoint.html

@@ -43,46 +43,15 @@ <h3 id="{{ anchorize (printf "%s-%s" .method .path) }}">{{ $displayName }}</h3>
                 {{ $schema := .schema }}
                 {{ if $schema }}
                     <h4>Request Body</h4>
-                    {{ if isset $schema "$ref" }}
-                        {{ $refPath := index $schema "$ref" }}
-                        {{ $refParts := split $refPath "/" }}
-                        {{ $schemaName := index $refParts (sub (len $refParts) 1) }}
-                        {{ $schemaDetails := "" }}
-                        {{ if isset $.openapi.components.schemas $schemaName }}
-                            {{ $schemaDetails = index $.openapi.components.schemas $schemaName }}
-                        {{ end }}
-                        {{ if $schemaDetails }}
-                            <div class="api-schema-label">Schema: <a href="/docs/reference/cloud-rest-api/schema/{{ $schemaName | urlize }}/">{{ $schemaName }}</a></div>
-                            {{ $resolved := partial "openapi/resolve-schema.html" (dict "schema" $schemaDetails "openapi" $.openapi) }}
-                            {{ if $resolved.properties }}
-                                <ul class="api-params">
-                                    {{ partial "openapi/property-rows.html" (dict
-                                        "properties" $resolved.properties
-                                        "required" $resolved.required
-                                        "openapi" $.openapi
-                                        "depth" 0
-                                        "maxDepth" 1
-                                    ) }}
-                                </ul>
-                            {{ end }}
-                        {{ end }}
-                    {{ else }}
-                        {{ $resolved := partial "openapi/resolve-schema.html" (dict "schema" $schema "openapi" $.openapi) }}
-                        {{ if $resolved.properties }}
-                        <ul class="api-params">
-                            {{ partial "openapi/property-rows.html" (dict
-                                "properties" $resolved.properties
-                                "required" ($resolved.required | default slice)
-                                "openapi" $.openapi
-                                "depth" 0
-                                "maxDepth" 1
-                            ) }}
-                        </ul>
-                    {{ end }}
+                    <div class="api-request-body">
+                        {{/* maxDepth 0: render top-level properties only. Nested $ref fields
+                             render as a link in the type column; users drill into the linked
+                             schema page rather than expanding inline. */}}
+                        {{ template "openapi/response-schema.html" (dict "schema" $schema "openapi" $.openapi "maxDepth" 0) }}
+                    </div>
                 {{ end }}
             {{ end }}
         {{ end }}
-    {{ end }}
 
         {{/* Request/response examples hidden for now — revisit once example
              quality is validated across the full public spec. */}}

layouts/partials/openapi/property-rows.html

@@ -8,7 +8,9 @@
 {{ $required := .required | default slice }}
 {{ $openapi := .openapi }}
 {{ $depth := .depth | default 0 }}
-{{ $maxDepth := .maxDepth | default 2 }}
+{{/* maxDepth is checked with isset so an explicit 0 isn't coerced to the default. */}}
+{{ $maxDepth := 2 }}
+{{ if isset . "maxDepth" }}{{ $maxDepth = .maxDepth }}{{ end }}
 
 {{ $sortedNames := slice }}
 {{ range $propName, $prop := $properties }}

layouts/partials/openapi/resolve-schema.html

@@ -58,9 +58,11 @@
 {{ else if isset $schema "$ref" }}
   {{ $refPath := index $schema "$ref" }}
   {{ $refParts := split $refPath "/" }}
-  {{ $schemaName = index $refParts (sub (len $refParts) 1) }}
-  {{ with index $openapi.components.schemas $schemaName }}
-    {{ $resolved := partial "openapi/resolve-schema.html" (dict "schema" . "openapi" $openapi "depth" (add $depth 1)) }}
+  {{ $candidateName := index $refParts (sub (len $refParts) 1) }}
+  {{ if isset $openapi.components.schemas $candidateName }}
+    {{ $schemaName = $candidateName }}
+    {{ $schemaDetails := index $openapi.components.schemas $candidateName }}
+    {{ $resolved := partial "openapi/resolve-schema.html" (dict "schema" $schemaDetails "openapi" $openapi "depth" (add $depth 1)) }}
     {{ $properties = $resolved.properties }}
     {{ $required = $resolved.required }}
     {{ $description = $resolved.description }}

layouts/partials/openapi/response-schema.html

@@ -1,5 +1,10 @@
 {{ define "openapi/response-schema.html" }}
 {{ if .schema }}
+    {{/* maxDepth defaults to 1 (one level of nested $ref expansion) for responses.
+         Callers can pass 0 to render top-level fields only and let the type-column
+         link be the drill-down (used by Request Body). */}}
+    {{ $maxDepth := 1 }}
+    {{ if isset . "maxDepth" }}{{ $maxDepth = .maxDepth }}{{ end }}
     {{ $resolved := partial "openapi/resolve-schema.html" (dict "schema" .schema "openapi" .openapi) }}
     {{ if $resolved.schemaName }}
         <div class="api-schema-label">Schema: <a href="/docs/reference/cloud-rest-api/schema/{{ $resolved.schemaName | urlize }}/">{{ $resolved.schemaName }}</a></div>
@@ -11,7 +16,7 @@
                 "required" $resolved.required
                 "openapi" .openapi
                 "depth" 0
-                "maxDepth" 1
+                "maxDepth" $maxDepth
             ) }}
         </ul>
     {{ end }}