Add support for an introduction page (#94)

Author: bourdakos1

cypress/integration/test.spec.ts

@@ -7,28 +7,35 @@
 
 describe("test", () => {
   before(() => {
-    cy.visit("/api");
+    cy.visit("/api/recursive");
   });
 
   it("renders query parameters", () => {
     cy.findByText(/query parameters/i).should("exist");
   });
 
-  it("loads when clicking on tabs", () => {
-    cy.on("uncaught:exception", () => {
-      // there is an uncaught error trying to load monaco in ci
-      return false;
-    });
+  it("loads issue 21 tab", () => {
+    checkTab(/issue 21/i, [], /missing summary/i);
+  });
+
+  it("loads cos tab", () => {
+    checkTab(/cos/i, [], /generating an iam token/i);
+  });
 
-    function checkTab(tab: RegExp, heading: RegExp) {
-      cy.get(".navbar").findByRole("link", { name: tab }).click();
-      cy.findByRole("heading", { name: heading, level: 1 }).should("exist");
-    }
+  it("loads yaml tab", () => {
+    checkTab(/yaml/i, [/api/i, /hello world/i], /hello world/i);
+  });
+
+  it("loads petstore tab", () => {
+    checkTab(
+      /petstore/i,
+      [/pet/i, /add a new pet to the store/i],
+      /add a new pet to the store/i
+    );
+  });
 
-    checkTab(/issue 21/i, /missing summary/i);
-    checkTab(/cos/i, /generating an iam token/i);
-    checkTab(/yaml/i, /hello world/i);
-    checkTab(/api/i, /recursive/i);
+  it("loads api tab", () => {
+    checkTab(/api/i, [/^pet$/i, /recursive/i], /recursive/i);
   });
 
   it("loads a page with authentication", () => {
@@ -39,3 +46,20 @@ describe("test", () => {
     cy.findByRole("button", { name: /authorize/i }).should("exist");
   });
 });
+
+function checkTab(tab: RegExp, links: RegExp[], heading: RegExp) {
+  cy.on("uncaught:exception", () => {
+    // there is an uncaught error trying to load monaco in ci
+    return false;
+  });
+
+  cy.get(".navbar").findByRole("link", { name: tab }).click();
+
+  for (let link of links) {
+    cy.get("nav.menu")
+      .findByRole("link", { name: link })
+      .click({ force: true }); // sometimes the sidebar items get covered by the navbar in CI.
+  }
+
+  cy.findByRole("heading", { name: heading, level: 1 }).should("exist");
+}

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

@@ -23,8 +23,9 @@ import {
 import chalk from "chalk";
 import { Configuration } from "webpack";
 
-import { createMD } from "./markdown";
-import { loadOpenapi } from "./openapi";
+import { createApiPageMD, createInfoPageMD } from "./markdown";
+import { readOpenapiFiles, processOpenapiFiles } from "./openapi";
+import { generateSidebars } from "./sidebars";
 import { PluginOptions, LoadedContent } from "./types";
 
 export default function pluginOpenAPI(
@@ -58,11 +59,12 @@ export default function pluginOpenAPI(
       const { routeBasePath } = options;
 
       try {
-        const loadedApi = await loadOpenapi(
-          contentPath,
+        const openapiFiles = await readOpenapiFiles(contentPath, {});
+        const loadedApi = await processOpenapiFiles(openapiFiles, {
           baseUrl,
-          routeBasePath
-        );
+          routeBasePath,
+          siteDir: context.siteDir,
+        });
         return { loadedApi };
       } catch (e) {
         console.error(chalk.red(`Loading of api failed for "${contentPath}"`));
@@ -72,86 +74,53 @@ export default function pluginOpenAPI(
 
     async contentLoaded({ content, actions }) {
       const { loadedApi } = content;
-      const { routeBasePath, apiLayoutComponent, apiItemComponent } = options;
+      const {
+        routeBasePath,
+        apiLayoutComponent,
+        apiItemComponent,
+        sidebarCollapsed,
+        sidebarCollapsible,
+      } = options;
       const { addRoute, createData } = actions;
 
       const sidebarName = `openapi-sidebar-${pluginId}`;
+      const sidebar = generateSidebars(loadedApi, {
+        sidebarCollapsible,
+        sidebarCollapsed,
+      });
 
-      const sidebar = loadedApi.map((category) => {
+      const promises = loadedApi.map(async (item) => {
+        const pageId = `site-${routeBasePath}-${item.id}`;
+
+        await createData(
+          `${docuHash(pageId)}.json`,
+          JSON.stringify(item, null, 2)
+        );
+
+        // TODO: "-content" should be inside hash to prevent name too long errors.
+        const markdown = await createData(
+          `${docuHash(pageId)}-content.mdx`,
+          item.type === "api" ? createApiPageMD(item) : createInfoPageMD(item)
+        );
         return {
-          type: "category",
-          label: category.title,
-          collapsible: options.sidebarCollapsible,
-          collapsed: options.sidebarCollapsed,
-          items: category.items.map((item) => {
-            return {
-              href: item.permalink,
-              label: item.title,
-              type: "link",
-              className: item.deprecated
-                ? "menu__list-item--deprecated"
-                : undefined,
-            };
-          }),
+          path: item.permalink,
+          component: apiItemComponent,
+          exact: true,
+          modules: {
+            content: markdown,
+          },
+          sidebar: sidebarName,
         };
       });
 
-      const promises = loadedApi.flatMap((section) => {
-        return section.items.map(async (item) => {
-          const { id, title, description, permalink, previous, next, ...api } =
-            item;
-
-          const pageId = `site-${routeBasePath}-${id}`;
-
-          await createData(
-            `${docuHash(pageId)}.json`,
-            JSON.stringify(
-              {
-                unversionedId: id,
-                id,
-                isDocsHomePage: false, // TODO: Where does this come from?
-                title,
-                description,
-                // source: "@site/docs/tutorial-basics/congratulations.md",
-                // sourceDirName: "tutorial-basics",
-                slug: "/" + id, // TODO: Should this really be prepended with "/"?
-                permalink,
-                frontMatter: {},
-                sidebar: sidebarName,
-                previous,
-                next,
-                api,
-              },
-              null,
-              2
-            )
-          );
-
-          // TODO: "-content" should be inside hash to prevent name too long errors.
-          const markdown = await createData(
-            `${docuHash(pageId)}-content.mdx`,
-            createMD(item)
-          );
-          return {
-            path: item.permalink,
-            component: apiItemComponent,
-            exact: true,
-            modules: {
-              content: markdown,
-            },
-            sidebar: sidebarName,
-          };
-        });
-      });
-
       // Important: the layout component should not end with /,
       // as it conflicts with the home doc
       // Workaround fix for https://github.com/facebook/docusaurus/issues/2917
       const apiBaseRoute = normalizeUrl([baseUrl, routeBasePath]);
       const basePath = apiBaseRoute === "/" ? "" : apiBaseRoute;
 
       async function rootRoute() {
-        const item = loadedApi[0].items[0];
+        const item = loadedApi[0];
         const pageId = `site-${routeBasePath}-${item.id}`;
 
         return {

packages/docusaurus-plugin-openapi/src/markdown/createVersionBadge.ts

@@ -0,0 +1,18 @@
+/* ============================================================================
+ * Copyright (c) Cloud Annotations
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import { create, guard } from "./utils";
+
+export function createVersionBadge(version: string | undefined) {
+  return guard(version, (version) => [
+    create("span", {
+      className: "theme-doc-version-badge badge badge--secondary",
+      children: `Version: ${escape(version)}`,
+    }),
+    `\n\n`,
+  ]);
+}

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

@@ -7,23 +7,26 @@
 
 import { escape } from "lodash";
 
-import { ApiItem } from "../types";
+import { ApiPageMetadata, InfoPageMetadata } from "../types";
 import { createDeprecationNotice } from "./createDeprecationNotice";
 import { createDescription } from "./createDescription";
 import { createParamsTable } from "./createParamsTable";
 import { createRequestBodyTable } from "./createRequestBodyTable";
 import { createStatusCodesTable } from "./createStatusCodesTable";
+import { createVersionBadge } from "./createVersionBadge";
 import { render } from "./utils";
 
-export function createMD({
+export function createApiPageMD({
   title,
-  deprecated,
-  "x-deprecated-description": deprecatedDescription,
-  description,
-  parameters,
-  requestBody,
-  responses,
-}: ApiItem) {
+  api: {
+    deprecated,
+    "x-deprecated-description": deprecatedDescription,
+    description,
+    parameters,
+    requestBody,
+    responses,
+  },
+}: ApiPageMetadata) {
   return render([
     `# ${escape(title)}\n\n`,
     createDeprecationNotice({ deprecated, description: deprecatedDescription }),
@@ -36,3 +39,13 @@ export function createMD({
     createStatusCodesTable({ responses }),
   ]);
 }
+
+export function createInfoPageMD({
+  info: { title, version, description },
+}: InfoPageMetadata) {
+  return render([
+    createVersionBadge(version),
+    `# ${escape(title)}\n\n`,
+    createDescription(description),
+  ]);
+}

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

@@ -5,4 +5,4 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-export { loadOpenapi } from "./load";
+export { readOpenapiFiles, processOpenapiFiles } from "./openapi";