feat: DevelopmentAPI Sidebar (#2211)

Objective:
We want to customize the sidebar of the OpenAPI docs and show something similar to the Stripe docs. If a user wants to exit the OpenAPI Reference then they can use the breadcrumbs navigation.

Author: NisanthanNanthakumar

src/components/developmentApiSidebar.tsx

@@ -0,0 +1,68 @@
+import React from "react";
+import { graphql, useStaticQuery } from "gatsby";
+import { useLocation } from "@reach/router";
+
+import SidebarLink from "./sidebarLink";
+import DynamicNav, { toTree } from "./dynamicNav";
+
+const query = graphql`
+  query DevelopmentApiNavQuery {
+    allSitePage(
+      filter: { path: { regex: "//development-api//" } }
+      sort: { fields: path }
+    ) {
+      nodes {
+        path
+        context {
+          title
+        }
+      }
+    }
+  }
+`;
+
+export default () => {
+  const data = useStaticQuery(query);
+  const tree = toTree(data.allSitePage.nodes.filter(n => !!n.context));
+  const endpoints = tree[0].children.filter(curr => curr.children.length > 1);
+  const location = useLocation();
+
+  const isActive = path => location && location.pathname.startsWith(path);
+
+  return (
+    <ul className="list-unstyled" data-sidebar-tree>
+      <DynamicNav
+        root="development-api"
+        title="API Reference"
+        tree={tree}
+        exclude={endpoints.map(elem => elem.node.path)}
+      />
+      <li className="mb-3" data-sidebar-branch>
+        <div
+          className="sidebar-title d-flex align-items-center mb-0"
+          data-sidebar-link
+        >
+          <h6>Endpoints</h6>
+        </div>
+        <ul className="list-unstyled" data-sidebar-tree>
+          {endpoints.map(({ node: { path, context: { title } }, children }) => (
+            <React.Fragment key={path}>
+              <SidebarLink to={path}>{title}</SidebarLink>
+              {isActive(path) && (
+                <div style={{ paddingLeft: "0.5rem" }}>
+                  {children
+                    .filter(({ node }) => !!node)
+                    .map(({ node: { path, context: { title } } }) => (
+                      <SidebarLink key={path} to={path}>
+                        {title}
+                      </SidebarLink>
+                    ))}
+                </div>
+              )}
+            </React.Fragment>
+          ))}
+        </ul>
+      </li>
+    </ul>
+  );
+};

src/components/dynamicNav.tsx

@@ -22,7 +22,7 @@ type Entity<T> = {
   node: Node | null;
 };
 
-interface EntityTree extends Entity<EntityTree> {}
+export interface EntityTree extends Entity<EntityTree> {}
 
 export const toTree = (nodeList: Node[]): EntityTree[] => {
   const result = [];

src/gatsby/createPages/createDevelopmentApiReference.ts

@@ -4,7 +4,7 @@ export default async ({ actions, graphql, reporter }) => {
   const data = await getDataOrPanic(
     `
           query {
-            allFile(filter: {absolutePath: {}, relativePath: {in: ["permissions.mdx", "auth.mdx", "index.mdx", "requests.mdx"]}, dir: {regex: "/api/"}}) {
+            allFile(filter: {absolutePath: {}, relativePath: {in: ["permissions.mdx", "auth.mdx", "index.mdx", "requests.mdx", "pagination.mdx"]}, dir: {regex: "/api/"}}) {
               nodes {
                 id
                 childMarkdownRemark {

src/templates/developmentAPI.js

@@ -4,6 +4,7 @@ import Prism from "prismjs";
 
 import BasePage from "~src/components/basePage";
 import SmartLink from "~src/components/smartLink";
+import DevelopmentApiSidebar from "~src/components/developmentApiSidebar";
 
 import "prismjs/components/prism-json";
 
@@ -71,7 +72,7 @@ export default props => {
   }, []);
 
   return (
-    <BasePage {...props}>
+    <BasePage sidebar={<DevelopmentApiSidebar />} {...props}>
       <div className="row">
         <div className="col-6">
           {data.summary && <p>{data.summary}</p>}

src/templates/developmentApiDoc.js

@@ -3,14 +3,15 @@ import { graphql } from "gatsby";
 
 import BasePage from "~src/components/basePage";
 import SmartLink from "~src/components/smartLink";
+import DevelopmentApiSidebar from "~src/components/developmentApiSidebar";
 
 export default props => {
   const {
     data: { allOpenApi },
   } = props;
 
   return (
-    <BasePage {...props}>
+    <BasePage sidebar={<DevelopmentApiSidebar />} {...props}>
       <ul>
         {allOpenApi.edges.map(({ node: { path } }) => (
           <li

src/templates/developmentApiReference.js

@@ -3,6 +3,7 @@ import { graphql } from "gatsby";
 
 import BasePage from "~src/components/basePage";
 import SmartLink from "~src/components/smartLink";
+import DevelopmentApiSidebar from "~src/components/developmentApiSidebar";
 
 export default props => {
   const {
@@ -19,7 +20,7 @@ export default props => {
   }, {});
 
   return (
-    <BasePage {...props}>
+    <BasePage sidebar={<DevelopmentApiSidebar />} {...props}>
       <h2>Endpoints</h2>
       <p>A full list of the currently supported API endpoints:</p>
       <ul>