docusaurus-plugin-openapi-docs 2.0.4 → 2.1.1

package/src/markdown/utils.ts

@@ -24,7 +24,7 @@ export function guard<T>(
   value: T | undefined,
   cb: (value: T) => Children
 ): string {
-  if (!!value) {
+  if (!!value || value === 0) {
     const children = cb(value);
     return render(children);
   }

package/src/openapi/__fixtures__/examples/openapi.yaml

@@ -11,3 +11,32 @@ paths:
       responses:
         200:
           description: OK
+
+tags:
+  - name: tag1
+    description: Everything about your Pets
+    x-displayName: Tag 1
+  - name: tag2
+    description: Tag 2 description
+    x-displayName: Tag 2
+  - name: tag3
+    description: Tag 3 description
+    x-displayName: Tag 3
+  - name: tag4
+    description: Tag 4 description
+    x-displayName: Tag 4
+
+x-tagGroups:
+  - name: Tag 1 & 2
+    tags:
+      - tag1
+      - tag2
+  - name: Trinity
+    tags:
+      - tag1
+      - tag2
+      - tag3
+  - name: Last Two
+    tags:
+      - tag3
+      - tag4

package/src/openapi/createRequestExample.ts

@@ -8,8 +8,8 @@
 import chalk from "chalk";
 import merge from "lodash/merge";
 
-import { mergeAllOf } from "../markdown/createSchema";
 import { SchemaObject } from "./types";
+import { mergeAllOf } from "../markdown/createSchema";
 
 interface OASTypeToTypeMap {
   string: string;

package/src/openapi/createResponseExample.ts

@@ -8,8 +8,8 @@
 import chalk from "chalk";
 import merge from "lodash/merge";
 
-import { mergeAllOf } from "../markdown/createSchema";
 import { SchemaObject } from "./types";
+import { mergeAllOf } from "../markdown/createSchema";
 
 interface OASTypeToTypeMap {
   string: string;

package/src/openapi/openapi.test.ts

@@ -28,6 +28,9 @@ describe("openapi", () => {
       const yaml = results.find((x) => x.source.endsWith("openapi.yaml"));
       expect(yaml).toBeTruthy();
       expect(yaml?.sourceDirName).toBe(".");
+
+      expect(yaml?.data.tags).toBeDefined();
+      expect(yaml?.data["x-tagGroups"]).toBeDefined();
     });
   });
 });

package/src/openapi/openapi.ts

@@ -18,18 +18,19 @@ import kebabCase from "lodash/kebabCase";
 import unionBy from "lodash/unionBy";
 import uniq from "lodash/uniq";
 
+import { sampleRequestFromSchema } from "./createRequestExample";
+import { OpenApiObject, TagGroupObject, TagObject } from "./types";
+import { loadAndResolveSpec } from "./utils/loadAndResolveSpec";
 import { isURL } from "../index";
 import {
   ApiMetadata,
   APIOptions,
   ApiPageMetadata,
   InfoPageMetadata,
+  SchemaPageMetadata,
   SidebarOptions,
   TagPageMetadata,
 } from "../types";
-import { sampleRequestFromSchema } from "./createRequestExample";
-import { OpenApiObject, TagObject } from "./types";
-import { loadAndResolveSpec } from "./utils/loadAndResolveSpec";
 
 /**
  * Convenience function for converting raw JSON to a Postman Collection object.
@@ -409,6 +410,46 @@ function createItems(
     }
   }
 
+  if (options?.showSchemas === true) {
+    // Gather schemas
+    for (let [schema, schemaObject] of Object.entries(
+      openapiData?.components?.schemas ?? {}
+    )) {
+      const baseIdSpaces =
+        schemaObject?.title?.replace(" ", "-").toLowerCase() ?? "";
+      const baseId = kebabCase(baseIdSpaces);
+
+      const schemaDescription = schemaObject.description;
+      let splitDescription: any;
+      if (schemaDescription) {
+        splitDescription = schemaDescription.match(/[^\r\n]+/g);
+      }
+
+      const schemaPage: PartialPage<SchemaPageMetadata> = {
+        type: "schema",
+        id: baseId,
+        infoId: infoId ?? "",
+        unversionedId: baseId,
+        title: schemaObject.title
+          ? schemaObject.title.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+          : schema,
+        description: schemaObject.description
+          ? schemaObject.description.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+          : "",
+        frontMatter: {
+          description: splitDescription
+            ? splitDescription[0]
+                .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                .replace(/\s+$/, "")
+            : "",
+        },
+        schema: schemaObject,
+      };
+
+      items.push(schemaPage);
+    }
+  }
+
   if (sidebarOptions?.categoryLinkSource === "tag") {
     // Get global tags
     const tags: TagObject[] = openapiData.tags ?? [];
@@ -471,7 +512,11 @@ function bindCollectionToApiItems(
       .getPath({ unresolved: true }) // unresolved returns "/:variableName" instead of "/<type>"
       .replace(/(?<![a-z0-9-_]+):([a-z0-9-_]+)/gi, "{$1}"); // replace "/:variableName" with "/{variableName}"
     const apiItem = items.find((item) => {
-      if (item.type === "info" || item.type === "tag") {
+      if (
+        item.type === "info" ||
+        item.type === "tag" ||
+        item.type === "schema"
+      ) {
         return false;
       }
       return item.api.path === path && item.api.method === method;
@@ -534,7 +579,7 @@ export async function processOpenapiFiles(
   files: OpenApiFiles[],
   options: APIOptions,
   sidebarOptions: SidebarOptions
-): Promise<[ApiMetadata[], TagObject[][]]> {
+): Promise<[ApiMetadata[], TagObject[][], TagGroupObject[]]> {
   const promises = files.map(async (file) => {
     if (file.data !== undefined) {
       const processedFile = await processOpenapiFile(
@@ -546,7 +591,8 @@ export async function processOpenapiFiles(
         ...item,
       }));
       const tags = processedFile[1];
-      return [itemsObjectsArray, tags];
+      const tagGroups = processedFile[2];
+      return [itemsObjectsArray, tags, tagGroups];
     }
     console.warn(
       chalk.yellow(
@@ -565,6 +611,7 @@ export async function processOpenapiFiles(
       // Remove undefined items due to transient parsing errors
       return x !== undefined;
     });
+
   const tags = metadata
     .map(function (x) {
       return x[1];
@@ -573,14 +620,29 @@ export async function processOpenapiFiles(
       // Remove undefined tags due to transient parsing errors
       return x !== undefined;
     });
-  return [items as ApiMetadata[], tags as TagObject[][]];
+
+  const tagGroups = metadata
+    .map(function (x) {
+      return x[2];
+    })
+    .flat()
+    .filter(function (x) {
+      // Remove undefined tags due to transient parsing errors
+      return x !== undefined;
+    });
+
+  return [
+    items as ApiMetadata[],
+    tags as TagObject[][],
+    tagGroups as TagGroupObject[],
+  ];
 }
 
 export async function processOpenapiFile(
   openapiData: OpenApiObject,
   options: APIOptions,
   sidebarOptions: SidebarOptions
-): Promise<[ApiMetadata[], TagObject[]]> {
+): Promise<[ApiMetadata[], TagObject[], TagGroupObject[]]> {
   const postmanCollection = await createPostmanCollection(openapiData);
   const items = createItems(openapiData, options, sidebarOptions);
 
@@ -590,7 +652,13 @@ export async function processOpenapiFile(
   if (openapiData.tags !== undefined) {
     tags = openapiData.tags;
   }
-  return [items, tags];
+
+  let tagGroups: TagGroupObject[] = [];
+  if (openapiData["x-tagGroups"] !== undefined) {
+    tagGroups = openapiData["x-tagGroups"];
+  }
+
+  return [items, tags, tagGroups];
 }
 
 // order for picking items as a display name of tags

package/src/openapi/types.ts

@@ -22,6 +22,7 @@ export interface OpenApiObject {
   externalDocs?: ExternalDocumentationObject;
   swagger?: string;
   "x-webhooks"?: PathsObject;
+  "x-tagGroups"?: TagGroupObject[];
 }
 
 export interface OpenApiObjectWithRef {
@@ -311,6 +312,11 @@ export interface TagObject {
   "x-displayName"?: string;
 }
 
+export interface TagGroupObject {
+  name: string;
+  tags: string[];
+}
+
 export interface ReferenceObject {
   $ref: string;
 }

package/src/openapi/utils/loadAndResolveSpec.ts

@@ -13,8 +13,8 @@ import chalk from "chalk";
 // @ts-ignore
 import { convertObj } from "swagger2openapi";
 
-import { OpenApiObject } from "../types";
 import { OpenAPIParser } from "./services/OpenAPIParser";
+import { OpenApiObject } from "../types";
 
 function serializer(replacer: any, cycleReplacer: any) {
   var stack: any = [],

package/src/openapi/utils/services/OpenAPIParser.ts

@@ -7,11 +7,11 @@
 
 // @ts-nocheck
 
+import { RedocNormalizedOptions } from "./RedocNormalizedOptions";
 import { OpenAPIRef, OpenAPISchema, OpenAPISpec, Referenced } from "../types";
 import { isArray, isBoolean } from "../utils/helpers";
 import { JsonPointer } from "../utils/JsonPointer";
 import { getDefinitionName, isNamedDefinition } from "../utils/openapi";
-import { RedocNormalizedOptions } from "./RedocNormalizedOptions";
 
 export type MergedOpenAPISchema = OpenAPISchema & { parentRefs?: string[] };
 

package/src/openapi/utils/utils/openapi.ts

@@ -9,6 +9,13 @@
 
 import { dirname } from "path";
 
+import {
+  isNumeric,
+  removeQueryString,
+  resolveUrl,
+  isArray,
+  isBoolean,
+} from "./helpers";
 import { OpenAPIParser } from "../services/OpenAPIParser";
 import {
   OpenAPIEncoding,
@@ -21,13 +28,6 @@ import {
   OpenAPIServer,
   Referenced,
 } from "../types";
-import {
-  isNumeric,
-  removeQueryString,
-  resolveUrl,
-  isArray,
-  isBoolean,
-} from "./helpers";
 
 function isWildcardStatusCode(
   statusCode: string | number

package/src/options.ts

@@ -8,7 +8,7 @@
 import { Joi } from "@docusaurus/utils-validation";
 
 const sidebarOptions = Joi.object({
-  groupPathsBy: Joi.string().valid("tag"),
+  groupPathsBy: Joi.string().valid("tag", "tagGroup"),
   categoryLinkSource: Joi.string().valid("tag", "info", "auto"),
   customProps: Joi.object(),
   sidebarCollapsible: Joi.boolean(),
@@ -37,6 +37,7 @@ export const OptionsSchema = Joi.object({
         showExtensions: Joi.boolean(),
         sidebarOptions: sidebarOptions,
         markdownGenerators: markdownGenerators,
+        showSchemas: Joi.boolean(),
         version: Joi.string().when("versions", {
           is: Joi.exist(),
           then: Joi.required(),

package/src/sidebars/index.ts

@@ -7,6 +7,7 @@
 
 import path from "path";
 
+import { ProcessedSidebarItem } from "@docusaurus/plugin-content-docs/lib/sidebars/types";
 import {
   ProcessedSidebar,
   SidebarItemCategory,
@@ -18,12 +19,13 @@ import clsx from "clsx";
 import { kebabCase } from "lodash";
 import uniq from "lodash/uniq";
 
-import { TagObject } from "../openapi/types";
+import { TagGroupObject, TagObject } from "../openapi/types";
 import type {
   SidebarOptions,
   APIOptions,
   ApiPageMetadata,
   ApiMetadata,
+  SchemaPageMetadata,
 } from "../types";
 
 function isApiItem(item: ApiMetadata): item is ApiMetadata {
@@ -34,6 +36,10 @@ function isInfoItem(item: ApiMetadata): item is ApiMetadata {
   return item.type === "info";
 }
 
+function isSchemaItem(item: ApiMetadata): item is ApiMetadata {
+  return item.type === "schema";
+}
+
 function groupByTags(
   items: ApiPageMetadata[],
   sidebarOptions: SidebarOptions,
@@ -55,6 +61,7 @@ function groupByTags(
 
   const apiItems = items.filter(isApiItem);
   const infoItems = items.filter(isInfoItem);
+  const schemaItems = items.filter(isSchemaItem);
   const intros = infoItems.map((item: any) => {
     return {
       id: item.id,
@@ -80,28 +87,35 @@ function groupByTags(
       apiTags.push(tag.name!);
     }
   });
-  apiTags = uniq(apiTags.concat(operationTags));
+  // apiTags = uniq(apiTags.concat(operationTags));
 
   const basePath = docPath
     ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
     : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
-  function createDocItem(item: ApiPageMetadata): SidebarItemDoc {
+  function createDocItem(
+    item: ApiPageMetadata | SchemaPageMetadata
+  ): SidebarItemDoc {
     const sidebar_label = item.frontMatter.sidebar_label;
     const title = item.title;
-    const id = item.id;
+    const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
+    const className =
+      item.type === "api"
+        ? clsx(
+            {
+              "menu__list-item--deprecated": item.api.deprecated,
+              "api-method": !!item.api.method,
+            },
+            item.api.method
+          )
+        : clsx({
+            "menu__list-item--deprecated": item.schema.deprecated,
+          });
     return {
       type: "doc" as const,
-      id:
-        basePath === "" || undefined ? `${item.id}` : `${basePath}/${item.id}`,
+      id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
       label: (sidebar_label as string) ?? title ?? id,
       customProps: customProps,
-      className: clsx(
-        {
-          "menu__list-item--deprecated": item.api.deprecated,
-          "api-method": !!item.api.method,
-        },
-        item.api.method
-      ),
+      className: className ? className : undefined,
     };
   }
 
@@ -201,13 +215,26 @@ function groupByTags(
     ];
   }
 
+  let schemas: SidebarItemCategory[] = [];
+  if (schemaItems.length > 0) {
+    schemas = [
+      {
+        type: "category" as const,
+        label: "Schemas",
+        collapsible: sidebarCollapsible!,
+        collapsed: sidebarCollapsed!,
+        items: schemaItems.map(createDocItem),
+      },
+    ];
+  }
+
   // Shift root intro doc to top of sidebar
   // TODO: Add input validation for categoryLinkSource options
   if (rootIntroDoc && categoryLinkSource !== "info") {
     tagged.unshift(rootIntroDoc as any);
   }
 
-  return [...tagged, ...untagged];
+  return [...tagged, ...untagged, ...schemas];
 }
 
 export default function generateSidebarSlice(
@@ -215,11 +242,38 @@ export default function generateSidebarSlice(
   options: APIOptions,
   api: ApiMetadata[],
   tags: TagObject[][],
-  docPath: string
+  docPath: string,
+  tagGroups?: TagGroupObject[]
 ) {
   let sidebarSlice: ProcessedSidebar = [];
 
-  if (sidebarOptions.groupPathsBy === "tag") {
+  if (sidebarOptions.groupPathsBy === "tagGroup") {
+    tagGroups?.forEach((tagGroup) => {
+      //filter tags only included in group
+      const filteredTags: TagObject[] = [];
+      tags[0].forEach((tag) => {
+        if (tagGroup.tags.includes(tag.name as string)) {
+          filteredTags.push(tag);
+        }
+      });
+
+      const groupCategory = {
+        type: "category" as const,
+        label: tagGroup.name,
+        collapsible: true,
+        collapsed: true,
+        items: groupByTags(
+          api as ApiPageMetadata[],
+          sidebarOptions,
+          options,
+          [filteredTags],
+          docPath
+        ),
+      } as ProcessedSidebarItem;
+
+      sidebarSlice.push(groupCategory);
+    });
+  } else if (sidebarOptions.groupPathsBy === "tag") {
     sidebarSlice = groupByTags(
       api as ApiPageMetadata[],
       sidebarOptions,
@@ -228,5 +282,6 @@ export default function generateSidebarSlice(
       docPath
     );
   }
+
   return sidebarSlice;
 }

package/src/types.ts

@@ -10,6 +10,7 @@ import type Request from "@paloaltonetworks/postman-collection";
 import {
   InfoObject,
   OperationObject,
+  SchemaObject,
   SecuritySchemeObject,
   TagObject,
 } from "./openapi/types";
@@ -44,12 +45,14 @@ export interface APIOptions {
   };
   proxy?: string;
   markdownGenerators?: MarkdownGenerator;
+  showSchemas?: boolean;
 }
 
 export interface MarkdownGenerator {
   createApiPageMD?: (pageData: ApiPageMetadata) => string;
   createInfoPageMD?: (pageData: InfoPageMetadata) => string;
   createTagPageMD?: (pageData: TagPageMetadata) => string;
+  createSchemaPageMD?: (pageData: SchemaPageMetadata) => string;
 }
 
 export interface SidebarOptions {
@@ -72,7 +75,11 @@ export interface LoadedContent {
   // loadedDocs: DocPageMetadata[]; TODO: cleanup
 }
 
-export type ApiMetadata = ApiPageMetadata | InfoPageMetadata | TagPageMetadata;
+export type ApiMetadata =
+  | ApiPageMetadata
+  | InfoPageMetadata
+  | TagPageMetadata
+  | SchemaPageMetadata;
 
 export interface ApiMetadataBase {
   sidebar?: string;
@@ -131,6 +138,19 @@ export interface TagPageMetadata extends ApiMetadataBase {
   markdown?: string;
 }
 
+export interface SchemaPageMetadata extends ApiMetadataBase {
+  type: "schema";
+  schema: SchemaObject;
+  markdown?: string;
+}
+
+export interface TagGroupPageMetadata extends ApiMetadataBase {
+  type: "tagGroup";
+  name: string;
+  tags: TagObject[];
+  markdown?: string;
+}
+
 export type ApiInfo = InfoObject;
 
 export interface ApiNavLink {