feat(theme): configurable schema expansion level (#1222)

demo/docusaurus.config.ts

@@ -271,6 +271,13 @@ const config: Config = {
       id: "announcementBar_2",
       content: "v5.0.0 is now available! Requires Docusaurus 3.10.0+",
     },
+    api: {
+      schemaExpansion: {
+        enabled: true,
+        default: 1,
+        max: 4,
+      },
+    },
   } satisfies Preset.ThemeConfig,
 
   plugins: [

demo/examples/tests/schemaExpansion.yaml

@@ -0,0 +1,140 @@
+openapi: 3.0.0
+info:
+  title: Schema Expansion Demo API
+  version: 1.0.0
+  description: |
+    Exercises the configurable schema expansion control. Endpoints below return
+    deeply nested envelope-wrapped payloads where the useful fields live a few
+    levels under `data`. The expansion pill control on each page should let
+    readers reveal those fields without manual clicking.
+
+    Tracks: https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/1222
+
+tags:
+  - name: expansion
+    description: Default schema expansion level demos
+
+paths:
+  /users/{id}:
+    get:
+      tags:
+        - expansion
+      summary: Get user (envelope-wrapped)
+      description: |
+        Wrapped in a typical `{ status, meta, data }` envelope where `data`
+        itself contains a nested `profile` object. With expansion level `1`,
+        `data` opens automatically; with level `2`, `profile` opens too.
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: A wrapped user payload.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UserEnvelope"
+  /users:
+    post:
+      tags:
+        - expansion
+      summary: Create user (nested request body)
+      description: |
+        The request body is also envelope-wrapped, exercising the expansion
+        control on the request side.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateUserEnvelope"
+      responses:
+        "201":
+          description: Created.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UserEnvelope"
+
+components:
+  schemas:
+    Status:
+      type: object
+      properties:
+        code:
+          type: integer
+        message:
+          type: string
+
+    Meta:
+      type: object
+      properties:
+        requestId:
+          type: string
+          format: uuid
+        timestamp:
+          type: string
+          format: date-time
+
+    Address:
+      type: object
+      properties:
+        street:
+          type: string
+        city:
+          type: string
+        country:
+          type: string
+
+    Profile:
+      type: object
+      properties:
+        displayName:
+          type: string
+        bio:
+          type: string
+        address:
+          $ref: "#/components/schemas/Address"
+
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+          format: email
+        profile:
+          $ref: "#/components/schemas/Profile"
+
+    UserEnvelope:
+      type: object
+      properties:
+        status:
+          $ref: "#/components/schemas/Status"
+        meta:
+          $ref: "#/components/schemas/Meta"
+        data:
+          $ref: "#/components/schemas/User"
+
+    CreateUserInput:
+      type: object
+      required:
+        - email
+      properties:
+        email:
+          type: string
+          format: email
+        profile:
+          $ref: "#/components/schemas/Profile"
+
+    CreateUserEnvelope:
+      type: object
+      properties:
+        meta:
+          $ref: "#/components/schemas/Meta"
+        data:
+          $ref: "#/components/schemas/CreateUserInput"

packages/docusaurus-theme-openapi-docs/src/theme/ApiItem/index.tsx

@@ -20,6 +20,7 @@ import DocItemLayout from "@theme/ApiItem/Layout";
 import CodeBlock from "@theme/CodeBlock";
 import type { Props } from "@theme/DocItem";
 import DocItemMetadata from "@theme/DocItem/Metadata";
+import { SchemaExpansionProvider } from "@theme/SchemaExpansion";
 import SkeletonLoader from "@theme/SkeletonLoader";
 import clsx from "clsx";
 import type {
@@ -177,18 +178,20 @@ export default function ApiItem(props: Props): JSX.Element {
           <DocItemMetadata />
           <DocItemLayout>
             <Provider store={store2}>
-              <div className={clsx("row", "theme-api-markdown")}>
-                <div className="col col--7 openapi-left-panel__container">
-                  <MDXComponent />
-                </div>
-                <div className="col col--5 openapi-right-panel__container">
-                  <BrowserOnly fallback={<SkeletonLoader size="lg" />}>
-                    {() => {
-                      return <ApiExplorer item={api} infoPath={infoPath} />;
-                    }}
-                  </BrowserOnly>
+              <SchemaExpansionProvider>
+                <div className={clsx("row", "theme-api-markdown")}>
+                  <div className="col col--7 openapi-left-panel__container">
+                    <MDXComponent />
+                  </div>
+                  <div className="col col--5 openapi-right-panel__container">
+                    <BrowserOnly fallback={<SkeletonLoader size="lg" />}>
+                      {() => {
+                        return <ApiExplorer item={api} infoPath={infoPath} />;
+                      }}
+                    </BrowserOnly>
+                  </div>
                 </div>
-              </div>
+              </SchemaExpansionProvider>
             </Provider>
           </DocItemLayout>
         </HtmlClassNameProvider>
@@ -200,16 +203,18 @@ export default function ApiItem(props: Props): JSX.Element {
         <HtmlClassNameProvider className={docHtmlClassName}>
           <DocItemMetadata />
           <DocItemLayout>
-            <div className={clsx("row", "theme-api-markdown")}>
-              <div className="col col--7 openapi-left-panel__container schema">
-                <MDXComponent />
-              </div>
-              <div className="col col--5 openapi-right-panel__container">
-                <CodeBlock language="json" title={`${frontMatter.title}`}>
-                  {JSON.stringify(sample, null, 2)}
-                </CodeBlock>
+            <SchemaExpansionProvider>
+              <div className={clsx("row", "theme-api-markdown")}>
+                <div className="col col--7 openapi-left-panel__container schema">
+                  <MDXComponent />
+                </div>
+                <div className="col col--5 openapi-right-panel__container">
+                  <CodeBlock language="json" title={`${frontMatter.title}`}>
+                    {JSON.stringify(sample, null, 2)}
+                  </CodeBlock>
+                </div>
               </div>
-            </div>
+            </SchemaExpansionProvider>
           </DocItemLayout>
         </HtmlClassNameProvider>
       </DocProvider>

packages/docusaurus-theme-openapi-docs/src/theme/RequestSchema/index.tsx

@@ -18,6 +18,7 @@ import {
   ResponseExamples,
 } from "@theme/ResponseExamples";
 import SchemaNode from "@theme/Schema";
+import SchemaExpansionControl from "@theme/SchemaExpansion";
 import SchemaTabs from "@theme/SchemaTabs";
 import SkeletonLoader from "@theme/SkeletonLoader";
 import TabItem from "@theme/TabItem";
@@ -77,24 +78,23 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
                       open={true}
                       style={style}
                       summary={
-                        <>
-                          <summary>
-                            <h3 className="openapi-markdown__details-summary-header-body">
-                              {translate({
-                                id: OPENAPI_REQUEST.BODY_TITLE,
-                                message: title,
-                              })}
-                              {body.required === true && (
-                                <span className="openapi-schema__required">
-                                  {translate({
-                                    id: OPENAPI_SCHEMA_ITEM.REQUIRED,
-                                    message: "required",
-                                  })}
-                                </span>
-                              )}
-                            </h3>
-                          </summary>
-                        </>
+                        <summary className="openapi-markdown__details-summary--with-control">
+                          <h3 className="openapi-markdown__details-summary-header-body">
+                            {translate({
+                              id: OPENAPI_REQUEST.BODY_TITLE,
+                              message: title,
+                            })}
+                            {body.required === true && (
+                              <span className="openapi-schema__required">
+                                {translate({
+                                  id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                                  message: "required",
+                                })}
+                              </span>
+                            )}
+                          </h3>
+                          <SchemaExpansionControl />
+                        </summary>
                       }
                     >
                       <div style={{ textAlign: "left", marginLeft: "1rem" }}>
@@ -164,27 +164,26 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
               open={true}
               style={style}
               summary={
-                <>
-                  <summary>
-                    <h3 className="openapi-markdown__details-summary-header-body">
-                      {translate({
-                        id: OPENAPI_REQUEST.BODY_TITLE,
-                        message: title,
-                      })}
-                      {firstBody.type === "array" && (
-                        <span style={{ opacity: "0.6" }}> array</span>
-                      )}
-                      {body.required && (
-                        <strong className="openapi-schema__required">
-                          {translate({
-                            id: OPENAPI_SCHEMA_ITEM.REQUIRED,
-                            message: "required",
-                          })}
-                        </strong>
-                      )}
-                    </h3>
-                  </summary>
-                </>
+                <summary className="openapi-markdown__details-summary--with-control">
+                  <h3 className="openapi-markdown__details-summary-header-body">
+                    {translate({
+                      id: OPENAPI_REQUEST.BODY_TITLE,
+                      message: title,
+                    })}
+                    {firstBody.type === "array" && (
+                      <span style={{ opacity: "0.6" }}> array</span>
+                    )}
+                    {body.required && (
+                      <strong className="openapi-schema__required">
+                        {translate({
+                          id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                          message: "required",
+                        })}
+                      </strong>
+                    )}
+                  </h3>
+                  <SchemaExpansionControl />
+                </summary>
               }
             >
               <div style={{ textAlign: "left", marginLeft: "1rem" }}>

packages/docusaurus-theme-openapi-docs/src/theme/ResponseSchema/index.tsx

@@ -18,6 +18,7 @@ import {
   ResponseExamples,
 } from "@theme/ResponseExamples";
 import SchemaNode from "@theme/Schema";
+import SchemaExpansionControl from "@theme/SchemaExpansion";
 import SchemaTabs from "@theme/SchemaTabs";
 import SkeletonLoader from "@theme/SkeletonLoader";
 import TabItem from "@theme/TabItem";
@@ -91,21 +92,20 @@ const ResponseSchemaComponent: React.FC<Props> = ({
                     open={true}
                     style={style}
                     summary={
-                      <>
-                        <summary>
-                          <strong className="openapi-markdown__details-summary-response">
-                            {title}
-                            {body.required === true && (
-                              <span className="openapi-schema__required">
-                                {translate({
-                                  id: OPENAPI_SCHEMA_ITEM.REQUIRED,
-                                  message: "required",
-                                })}
-                              </span>
-                            )}
-                          </strong>
-                        </summary>
-                      </>
+                      <summary className="openapi-markdown__details-summary--with-control">
+                        <strong className="openapi-markdown__details-summary-response">
+                          {title}
+                          {body.required === true && (
+                            <span className="openapi-schema__required">
+                              {translate({
+                                id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                                message: "required",
+                              })}
+                            </span>
+                          )}
+                        </strong>
+                        <SchemaExpansionControl />
+                      </summary>
                     }
                   >
                     <div style={{ textAlign: "left", marginLeft: "1rem" }}>