Migrate schema page to Schema component and refactor layout (#1001)

* use schema component to render standalone schemas

* add sample from schema to schema page frontmatter

* implmenet two panel view for schema pages

* add sample to schema page template

* allow createSchemaPageMd markdown generator type

* remove unused import

* adapt layout column width for schema pages

* remove browseronly wrapper

* revert to codeblock component

* comment out col max-width

* upgrade sass and sass-loader

* revert col max-width

* hide toc for schema pages

* use media to apply conditional bottom margin

packages/docusaurus-plugin-openapi-docs/src/index.ts

@@ -278,7 +278,11 @@ title: "{{{title}}}"
 description: "{{{frontMatter.description}}}"
 sidebar_label: "{{{title}}}"
 hide_title: true
+{{#schema}}
+hide_table_of_contents: true
+{{/schema}}
 schema: true
+sample: {{{frontMatter.sample}}}
 custom_edit_url: null
 ---
 

packages/docusaurus-plugin-openapi-docs/src/markdown/index.ts

@@ -19,7 +19,6 @@ import { createMethodEndpoint } from "./createMethodEndpoint";
 import { createParamsDetails } from "./createParamsDetails";
 import { createRequestBodyDetails } from "./createRequestBodyDetails";
 import { createRequestHeader } from "./createRequestHeader";
-import { createNodes } from "./createSchema";
 import { createStatusCodes } from "./createStatusCodes";
 import { createTermsOfService } from "./createTermsOfService";
 import { createVendorExtensions } from "./createVendorExtensions";
@@ -133,15 +132,13 @@ export function createTagPageMD({ tag: { description } }: TagPageMetadata) {
 export function createSchemaPageMD({ schema }: SchemaPageMetadata) {
   const { title = "", description } = schema;
   return render([
-    `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
-    `import SchemaItem from "@theme/SchemaItem";\n`,
-    `import SchemaTabs from "@theme/SchemaTabs";\n`,
-    `import Heading from "@theme/Heading";\n`,
-    `import TabItem from "@theme/TabItem";\n\n`,
+    `import Schema from "@theme/Schema";\n`,
+    `import Heading from "@theme/Heading";\n\n`,
     createHeading(title.replace(lessThan, "<").replace(greaterThan, ">")),
     createDescription(description),
-    create("ul", {
-      children: createNodes(schema, "response"),
+    create("Schema", {
+      schema: schema,
+      schemaType: "response",
     }),
   ]);
 }

packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts

@@ -30,6 +30,7 @@ import {
   SidebarOptions,
   TagPageMetadata,
 } from "../types";
+import { sampleResponseFromSchema } from "./createResponseExample";
 import { loadAndResolveSpec } from "./utils/loadAndResolveSpec";
 
 /**
@@ -451,6 +452,7 @@ function createItems(
                   .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
                   .replace(/\s+$/, "")
               : "",
+            sample: JSON.stringify(sampleResponseFromSchema(schemaObject)),
           },
           schema: schemaObject,
         };

packages/docusaurus-plugin-openapi-docs/src/options.ts

@@ -24,6 +24,7 @@ const markdownGenerators = Joi.object({
   createApiPageMD: Joi.function(),
   createInfoPageMD: Joi.function(),
   createTagPageMD: Joi.function(),
+  createSchemaPageMD: Joi.function(),
 });
 
 export const OptionsSchema = Joi.object({

packages/docusaurus-theme-openapi-docs/package.json

@@ -59,8 +59,8 @@
     "react-redux": "^7.2.0",
     "rehype-raw": "^6.1.1",
     "remark-gfm": "3.0.1",
-    "sass": "^1.58.1",
-    "sass-loader": "^13.3.2",
+    "sass": "^1.80.4",
+    "sass-loader": "^16.0.2",
     "webpack": "^5.61.0",
     "xml-formatter": "^2.6.1"
   },

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

@@ -52,6 +52,7 @@ export default function DocItemLayout({ children }: Props): JSX.Element {
   const { metadata } = useDoc();
   const { frontMatter } = useDoc();
   const api = frontMatter.api;
+  const schema = frontMatter.schema;
   return (
     <div className="row">
       <div className={clsx("col", !docTOC.hidden && styles.docItemCol)}>
@@ -64,13 +65,15 @@ export default function DocItemLayout({ children }: Props): JSX.Element {
             {docTOC.mobile}
             <DocItemContent>{children}</DocItemContent>
             <div className="row">
-              <div className={clsx("col", api ? "col--7" : "col--12")}>
+              <div
+                className={clsx("col", api || schema ? "col--7" : "col--12")}
+              >
                 <DocItemFooter />
               </div>
             </div>
           </article>
           <div className="row">
-            <div className={clsx("col", api ? "col--7" : "col--12")}>
+            <div className={clsx("col", api || schema ? "col--7" : "col--12")}>
               <DocItemPaginator />
             </div>
           </div>

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

@@ -18,6 +18,7 @@ import useIsBrowser from "@docusaurus/useIsBrowser";
 import { createAuth } from "@theme/ApiExplorer/Authorization/slice";
 import { createPersistanceMiddleware } from "@theme/ApiExplorer/persistanceMiddleware";
 import DocItemLayout from "@theme/ApiItem/Layout";
+import CodeBlock from "@theme/CodeBlock";
 import type { Props } from "@theme/DocItem";
 import DocItemMetadata from "@theme/DocItem/Metadata";
 import SkeletonLoader from "@theme/SkeletonLoader";
@@ -47,6 +48,10 @@ interface SchemaFrontMatter extends DocFrontMatter {
   readonly schema?: boolean;
 }
 
+interface SampleFrontMatter extends DocFrontMatter {
+  readonly sample?: any;
+}
+
 // @ts-ignore
 export default function ApiItem(props: Props): JSX.Element {
   const docHtmlClassName = `docs-doc-id-${props.content.metadata.id}`;
@@ -55,6 +60,7 @@ export default function ApiItem(props: Props): JSX.Element {
   const { info_path: infoPath } = frontMatter as DocFrontMatter;
   let { api } = frontMatter as ApiFrontMatter;
   const { schema } = frontMatter as SchemaFrontMatter;
+  const { sample } = frontMatter as SampleFrontMatter;
   // decompress and parse
   if (api) {
     try {
@@ -172,9 +178,14 @@ export default function ApiItem(props: Props): JSX.Element {
           <DocItemMetadata />
           <DocItemLayout>
             <div className={clsx("row", "theme-api-markdown")}>
-              <div className="col col--12">
+              <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>
           </DocItemLayout>
         </HtmlClassNameProvider>

packages/docusaurus-theme-openapi-docs/src/theme/styles.scss

@@ -93,16 +93,16 @@
   height: 100%;
 }
 
-@media (min-width: 997px) {
-  .docItemCol {
-    max-width: 75% !important;
-  }
-
-  /* Prevent hydration FOUC, as the mobile TOC needs to be server-rendered */
-  .tocMobile {
-    display: none;
-  }
-}
+// @media (min-width: 997px) {
+//   .docItemCol {
+//     max-width: 75% !important;
+//   }
+
+//   /* Prevent hydration FOUC, as the mobile TOC needs to be server-rendered */
+//   .tocMobile {
+//     display: none;
+//   }
+// }
 
 /* Begin OpenAPI theme styles */
 // [data-theme="dark"] {
@@ -161,6 +161,12 @@
   border-right: thin solid var(--ifm-toc-border-color);
 }
 
+@media (max-width: 997px) {
+  .schema {
+    margin-bottom: 1rem;
+  }
+}
+
 .openapi-tabs__heading {
   margin-bottom: 1rem;
 }

yarn.lock

@@ -2866,6 +2866,89 @@
   dependencies:
     "@octokit/openapi-types" "^18.0.0"
 
+"@parcel/watcher-android-arm64@2.4.1":
+  version "2.4.1"
+  resolved "https://registry.yarnpkg.com/@parcel/watcher-android-arm64/-/watcher-android-arm64-2.4.1.tgz#c2c19a3c442313ff007d2d7a9c2c1dd3e1c9ca84"
+  integrity sha512-LOi/WTbbh3aTn2RYddrO8pnapixAziFl6SMxHM69r3tvdSm94JtCenaKgk1GRg5FJ5wpMCpHeW+7yqPlvZv7kg==
+
+"@parcel/watcher-darwin-arm64@2.4.1":
+  version "2.4.1"
+  resolved "https://registry.yarnpkg.com/@parcel/watcher-darwin-arm64/-/watcher-darwin-arm64-2.4.1.tgz#c817c7a3b4f3a79c1535bfe54a1c2818d9ffdc34"
+  integrity sha512-ln41eihm5YXIY043vBrrHfn94SIBlqOWmoROhsMVTSXGh0QahKGy77tfEywQ7v3NywyxBBkGIfrWRHm0hsKtzA==
+
+"@parcel/watcher-darwin-x64@2.4.1":
+  version "2.4.1"
+  resolved "https://registry.yarnpkg.com/@parcel/watcher-darwin-x64/-/watcher-darwin-x64-2.4.1.tgz#1a3f69d9323eae4f1c61a5f480a59c478d2cb020"
+  integrity sha512-yrw81BRLjjtHyDu7J61oPuSoeYWR3lDElcPGJyOvIXmor6DEo7/G2u1o7I38cwlcoBHQFULqF6nesIX3tsEXMg==
+
+"@parcel/watcher-freebsd-x64@2.4.1":
+  version "2.4.1"
+  resolved "https://registry.yarnpkg.com/@parcel/watcher-freebsd-x64/-/watcher-freebsd-x64-2.4.1.tgz#0d67fef1609f90ba6a8a662bc76a55fc93706fc8"
+  integrity sha512-TJa3Pex/gX3CWIx/Co8k+ykNdDCLx+TuZj3f3h7eOjgpdKM+Mnix37RYsYU4LHhiYJz3DK5nFCCra81p6g050w==
+
+"@parcel/watcher-linux-arm-glibc@2.4.1":
+  version "2.4.1"
+  resolved "https://registry.yarnpkg.com/@parcel/watcher-linux-arm-glibc/-/watcher-linux-arm-glibc-2.4.1.tgz#ce5b340da5829b8e546bd00f752ae5292e1c702d"
+  integrity sha512-4rVYDlsMEYfa537BRXxJ5UF4ddNwnr2/1O4MHM5PjI9cvV2qymvhwZSFgXqbS8YoTk5i/JR0L0JDs69BUn45YA==
+
+"@parcel/watcher-linux-arm64-glibc@2.4.1":
+  version "2.4.1"
+  resolved "https://registry.yarnpkg.com/@parcel/watcher-linux-arm64-glibc/-/watcher-linux-arm64-glibc-2.4.1.tgz#6d7c00dde6d40608f9554e73998db11b2b1ff7c7"
+  integrity sha512-BJ7mH985OADVLpbrzCLgrJ3TOpiZggE9FMblfO65PlOCdG++xJpKUJ0Aol74ZUIYfb8WsRlUdgrZxKkz3zXWYA==
+
+"@parcel/watcher-linux-arm64-musl@2.4.1":
+  version "2.4.1"
+  resolved "https://registry.yarnpkg.com/@parcel/watcher-linux-arm64-musl/-/watcher-linux-arm64-musl-2.4.1.tgz#bd39bc71015f08a4a31a47cd89c236b9d6a7f635"
+  integrity sha512-p4Xb7JGq3MLgAfYhslU2SjoV9G0kI0Xry0kuxeG/41UfpjHGOhv7UoUDAz/jb1u2elbhazy4rRBL8PegPJFBhA==
+
+"@parcel/watcher-linux-x64-glibc@2.4.1":
+  version "2.4.1"
+  resolved "https://registry.yarnpkg.com/@parcel/watcher-linux-x64-glibc/-/watcher-linux-x64-glibc-2.4.1.tgz#0ce29966b082fb6cdd3de44f2f74057eef2c9e39"
+  integrity sha512-s9O3fByZ/2pyYDPoLM6zt92yu6P4E39a03zvO0qCHOTjxmt3GHRMLuRZEWhWLASTMSrrnVNWdVI/+pUElJBBBg==
+
+"@parcel/watcher-linux-x64-musl@2.4.1":
+  version "2.4.1"
+  resolved "https://registry.yarnpkg.com/@parcel/watcher-linux-x64-musl/-/watcher-linux-x64-musl-2.4.1.tgz#d2ebbf60e407170bb647cd6e447f4f2bab19ad16"
+  integrity sha512-L2nZTYR1myLNST0O632g0Dx9LyMNHrn6TOt76sYxWLdff3cB22/GZX2UPtJnaqQPdCRoszoY5rcOj4oMTtp5fQ==
+
+"@parcel/watcher-win32-arm64@2.4.1":
+  version "2.4.1"
+  resolved "https://registry.yarnpkg.com/@parcel/watcher-win32-arm64/-/watcher-win32-arm64-2.4.1.tgz#eb4deef37e80f0b5e2f215dd6d7a6d40a85f8adc"
+  integrity sha512-Uq2BPp5GWhrq/lcuItCHoqxjULU1QYEcyjSO5jqqOK8RNFDBQnenMMx4gAl3v8GiWa59E9+uDM7yZ6LxwUIfRg==
+
+"@parcel/watcher-win32-ia32@2.4.1":
+  version "2.4.1"
+  resolved "https://registry.yarnpkg.com/@parcel/watcher-win32-ia32/-/watcher-win32-ia32-2.4.1.tgz#94fbd4b497be39fd5c8c71ba05436927842c9df7"
+  integrity sha512-maNRit5QQV2kgHFSYwftmPBxiuK5u4DXjbXx7q6eKjq5dsLXZ4FJiVvlcw35QXzk0KrUecJmuVFbj4uV9oYrcw==
+
+"@parcel/watcher-win32-x64@2.4.1":
+  version "2.4.1"
+  resolved "https://registry.yarnpkg.com/@parcel/watcher-win32-x64/-/watcher-win32-x64-2.4.1.tgz#4bf920912f67cae5f2d264f58df81abfea68dadf"
+  integrity sha512-+DvS92F9ezicfswqrvIRM2njcYJbd5mb9CUgtrHCHmvn7pPPa+nMDRu1o1bYYz/l5IB2NVGNJWiH7h1E58IF2A==
+
+"@parcel/watcher@^2.4.1":
+  version "2.4.1"
+  resolved "https://registry.yarnpkg.com/@parcel/watcher/-/watcher-2.4.1.tgz#a50275151a1bb110879c6123589dba90c19f1bf8"
+  integrity sha512-HNjmfLQEVRZmHRET336f20H/8kOozUGwk7yajvsonjNxbj2wBTK1WsQuHkD5yYh9RxFGL2EyDHryOihOwUoKDA==
+  dependencies:
+    detect-libc "^1.0.3"
+    is-glob "^4.0.3"
+    micromatch "^4.0.5"
+    node-addon-api "^7.0.0"
+  optionalDependencies:
+    "@parcel/watcher-android-arm64" "2.4.1"
+    "@parcel/watcher-darwin-arm64" "2.4.1"
+    "@parcel/watcher-darwin-x64" "2.4.1"
+    "@parcel/watcher-freebsd-x64" "2.4.1"
+    "@parcel/watcher-linux-arm-glibc" "2.4.1"
+    "@parcel/watcher-linux-arm64-glibc" "2.4.1"
+    "@parcel/watcher-linux-arm64-musl" "2.4.1"
+    "@parcel/watcher-linux-x64-glibc" "2.4.1"
+    "@parcel/watcher-linux-x64-musl" "2.4.1"
+    "@parcel/watcher-win32-arm64" "2.4.1"
+    "@parcel/watcher-win32-ia32" "2.4.1"
+    "@parcel/watcher-win32-x64" "2.4.1"
+
 "@pkgjs/parseargs@^0.11.0":
   version "0.11.0"
   resolved "https://registry.yarnpkg.com/@pkgjs/parseargs/-/parseargs-0.11.0.tgz#a77ea742fab25775145434eb1d2328cf5013ac33"
@@ -6594,6 +6677,11 @@ detect-indent@^5.0.0:
   resolved "https://registry.yarnpkg.com/detect-indent/-/detect-indent-5.0.0.tgz#3871cc0a6a002e8c3e5b3cf7f336264675f06b9d"
   integrity sha512-rlpvsxUtM0PQvy9iZe640/IWwWYyBsTApREbA1pHOpmOUIl9MkP/U4z7vTtg4Oaojvqhxt7sdufnT0EzGaR31g==
 
+detect-libc@^1.0.3:
+  version "1.0.3"
+  resolved "https://registry.yarnpkg.com/detect-libc/-/detect-libc-1.0.3.tgz#fa137c4bd698edf55cd5cd02ac559f91a4c4ba9b"
+  integrity sha512-pGjwhsmsp4kL2RTz08wcOlGN83otlqHeD/Z5T8GXZB+/YcpQ/dgo+lbU8ZsGxV0HIvqqxo9l7mqYwyYMD9bKDg==
+
 detect-newline@^3.0.0:
   version "3.1.0"
   resolved "https://registry.yarnpkg.com/detect-newline/-/detect-newline-3.1.0.tgz#576f5dfc63ae1a192ff192d8ad3af6308991b651"
@@ -12503,6 +12591,11 @@ no-case@^3.0.4:
     lower-case "^2.0.2"
     tslib "^2.0.3"
 
+node-addon-api@^7.0.0:
+  version "7.1.1"
+  resolved "https://registry.yarnpkg.com/node-addon-api/-/node-addon-api-7.1.1.tgz#1aba6693b0f255258a049d621329329322aad558"
+  integrity sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==
+
 node-emoji@^2.1.0:
   version "2.1.3"
   resolved "https://registry.yarnpkg.com/node-emoji/-/node-emoji-2.1.3.tgz#93cfabb5cc7c3653aa52f29d6ffb7927d8047c06"
@@ -15160,18 +15253,19 @@ sass-loader@^10.1.1:
     schema-utils "^3.0.0"
     semver "^7.3.2"
 
-sass-loader@^13.3.2:
-  version "13.3.3"
-  resolved "https://registry.yarnpkg.com/sass-loader/-/sass-loader-13.3.3.tgz#60df5e858788cffb1a3215e5b92e9cba61e7e133"
-  integrity sha512-mt5YN2F1MOZr3d/wBRcZxeFgwgkH44wVc2zohO2YF6JiOMkiXe4BYRZpSu2sO1g71mo/j16txzUhsKZlqjVGzA==
+sass-loader@^16.0.2:
+  version "16.0.2"
+  resolved "https://registry.yarnpkg.com/sass-loader/-/sass-loader-16.0.2.tgz#e581bc13d7cb5090e27f155c6aa2855c08cafe86"
+  integrity sha512-Ll6iXZ1EYwYT19SqW4mSBb76vSSi8JgzElmzIerhEGgzB5hRjDQIWsPmuk1UrAXkR16KJHqVY0eH+5/uw9Tmfw==
   dependencies:
     neo-async "^2.6.2"
 
-sass@^1.58.1:
-  version "1.79.4"
-  resolved "https://registry.yarnpkg.com/sass/-/sass-1.79.4.tgz#f9c45af35fbeb53d2c386850ec842098d9935267"
-  integrity sha512-K0QDSNPXgyqO4GZq2HO5Q70TLxTH6cIT59RdoCHMivrC8rqzaTw5ab9prjz9KUN1El4FLXrBXJhik61JR4HcGg==
+sass@^1.80.4:
+  version "1.80.4"
+  resolved "https://registry.yarnpkg.com/sass/-/sass-1.80.4.tgz#bc0418fd796cad2f1a1309d8b4d7fe44b7027de0"
+  integrity sha512-rhMQ2tSF5CsuuspvC94nPM9rToiAFw2h3JTrLlgmNw1MH79v8Cr3DH6KF6o6r+8oofY3iYVPUf66KzC8yuVN1w==
   dependencies:
+    "@parcel/watcher" "^2.4.1"
     chokidar "^4.0.0"
     immutable "^4.0.0"
     source-map-js ">=0.6.2 <2.0.0"