docusaurus-plugin-openapi-docs 1.1.2 → 1.1.5

package/src/openapi/openapi.ts

@@ -13,7 +13,8 @@ import sdk from "@paloaltonetworks/postman-collection";
 import Collection from "@paloaltonetworks/postman-collection";
 import chalk from "chalk";
 import fs from "fs-extra";
-import { kebabCase } from "lodash";
+import cloneDeep from "lodash/cloneDeep";
+import kebabCase from "lodash/kebabCase";
 
 import { isURL } from "../index";
 import {
@@ -54,7 +55,7 @@ async function createPostmanCollection(
   openapiData: OpenApiObject
 ): Promise<Collection> {
   // Create copy of openapiData
-  const data = Object.assign({}, openapiData) as OpenApiObject;
+  const data = cloneDeep(openapiData) as OpenApiObject;
 
   // Including `servers` breaks postman, so delete all of them.
   delete data.servers;
@@ -102,7 +103,6 @@ function createItems(
           unversionedId: tagId,
           title: description ?? "",
           description: description ?? "",
-          slug: "/" + tagId,
           frontMatter: {},
           tag: {
             ...tag,
@@ -120,15 +120,14 @@ function createItems(
       unversionedId: infoId,
       title: openapiData.info.title,
       description: openapiData.info.description,
-      slug: "/" + infoId,
       frontMatter: {},
       securitySchemes: openapiData.components?.securitySchemes,
       info: {
         ...openapiData.info,
-        tags: openapiData.tags?.map((tagName) =>
-          getTagDisplayName(tagName.name!, openapiData.tags ?? [])
-        ),
+        tags: openapiData.tags,
         title: openapiData.info.title ?? "Introduction",
+        logo: openapiData.info["x-logo"]! as any,
+        darkLogo: openapiData.info["x-dark-logo"]! as any,
       },
     };
     items.push(infoPage);
@@ -174,6 +173,18 @@ function createItems(
         jsonRequestBodyExample = sampleFromSchema(body.schema);
       }
 
+      // Handle vendor JSON media types
+      const bodyContent = operationObject.requestBody?.content;
+      if (bodyContent) {
+        const firstBodyContentKey = Object.keys(bodyContent)[0];
+        if (firstBodyContentKey.endsWith("+json")) {
+          const firstBody = bodyContent[firstBodyContentKey];
+          if (firstBody?.schema) {
+            jsonRequestBodyExample = sampleFromSchema(firstBody.schema);
+          }
+        }
+      }
+
       // TODO: Don't include summary temporarilly
       const { summary, ...defaults } = operationObject;
 
@@ -184,13 +195,10 @@ function createItems(
         unversionedId: baseId,
         title: title,
         description: description ?? "",
-        slug: "/" + baseId,
         frontMatter: {},
         api: {
           ...defaults,
-          tags: operationObject.tags?.map((tagName) =>
-            getTagDisplayName(tagName, openapiData.tags ?? [])
-          ),
+          tags: operationObject.tags,
           method,
           path,
           servers,
@@ -291,7 +299,7 @@ export async function readOpenapiFiles(
 export async function processOpenapiFiles(
   files: OpenApiFiles[],
   sidebarOptions: SidebarOptions
-): Promise<[ApiMetadata[], TagObject[]]> {
+): Promise<[ApiMetadata[], TagObject[][]]> {
   const promises = files.map(async (file) => {
     if (file.data !== undefined) {
       const processedFile = await processOpenapiFile(file.data, sidebarOptions);
@@ -326,7 +334,7 @@ export async function processOpenapiFiles(
       // Remove undefined tags due to transient parsing errors
       return x !== undefined;
     });
-  return [items as ApiMetadata[], tags as TagObject[]];
+  return [items as ApiMetadata[], tags as TagObject[][]];
 }
 
 export async function processOpenapiFile(

package/src/openapi/types.ts

@@ -41,7 +41,15 @@ export interface InfoObject {
   contact?: ContactObject;
   license?: LicenseObject;
   version: string;
-  tags?: String[];
+  tags?: TagObject[];
+  "x-logo"?: LogoObject;
+  "x-dark-logo"?: LogoObject;
+  logo?: LogoObject;
+  darkLogo?: LogoObject;
+}
+
+export interface LogoObject {
+  url?: string;
 }
 
 export interface ContactObject {

package/src/openapi/utils/loadAndResolveSpec.ts

@@ -14,6 +14,7 @@ import chalk from "chalk";
 import { convertObj } from "swagger2openapi";
 
 import { OpenApiObject } from "../types";
+import { OpenAPIParser } from "./services/OpenAPIParser";
 
 function serializer(replacer: any, cycleReplacer: any) {
   var stack: any = [],
@@ -26,6 +27,18 @@ function serializer(replacer: any, cycleReplacer: any) {
     };
 
   return function (key: any, value: any) {
+    // Resolve discriminator ref pointers
+    if (value?.discriminator !== undefined) {
+      const parser = new OpenAPIParser(stack[0]);
+      for (let [k, v] of Object.entries(value.discriminator.mapping)) {
+        const discriminator = k as string;
+        if (typeof v === "string" && v.charAt(0) === "#") {
+          const ref = v as string;
+          const resolvedRef = parser.byRef(ref);
+          value.discriminator.mapping[discriminator] = resolvedRef;
+        }
+      }
+    }
     if (stack.length > 0) {
       // @ts-ignore
       var thisPos = stack.indexOf(this);

package/src/sidebars/index.ts

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import path from "path";
+
 import {
   ProcessedSidebar,
   SidebarItemCategory,
@@ -35,7 +37,7 @@ function groupByTags(
   items: ApiPageMetadata[],
   sidebarOptions: SidebarOptions,
   options: APIOptions,
-  tags: TagObject[],
+  tags: TagObject[][],
   docPath: string
 ): ProcessedSidebar {
   const { outputDir, label } = options;
@@ -58,12 +60,20 @@ function groupByTags(
   });
 
   // TODO: make sure we only take the first tag
-  const apiTags = uniq(
+  const operationTags = uniq(
     apiItems
       .flatMap((item) => item.api.tags)
       .filter((item): item is string => !!item)
   );
 
+  // Only include operation tags that are globally defined
+  const apiTags: string[] = [];
+  tags.flat().forEach((tag) => {
+    if (operationTags.includes(tag.name!)) {
+      apiTags.push(tag.name!);
+    }
+  });
+
   const basePath = docPath
     ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
     : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
@@ -105,7 +115,7 @@ function groupByTags(
       );
       const tagObject = tags.flat().find(
         (t) =>
-          (tag === t.name || tag === t["x-displayName"]) ?? {
+          tag === t.name ?? {
             name: tag,
             description: `${tag} Index`,
           }
@@ -139,14 +149,14 @@ function groupByTags(
           type: "generated-index" as "generated-index",
           title: tag,
           slug: label
-            ? "/category/" + kebabCase(label) + "/" + kebabCase(tag)
-            : "/category/" + kebabCase(tag),
+            ? path.join("/category", basePath, kebabCase(label), kebabCase(tag))
+            : path.join("/category", basePath, kebabCase(tag)),
         } as SidebarItemCategoryLinkConfig;
       }
 
       return {
         type: "category" as const,
-        label: tag,
+        label: tagObject?.["x-displayName"] ?? tag,
         link: linkConfig,
         collapsible: sidebarCollapsible,
         collapsed: sidebarCollapsed,
@@ -189,7 +199,7 @@ export default function generateSidebarSlice(
   sidebarOptions: SidebarOptions,
   options: APIOptions,
   api: ApiMetadata[],
-  tags: TagObject[],
+  tags: TagObject[][],
   docPath: string
 ) {
   let sidebarSlice: ProcessedSidebar = [];

package/src/types.ts

@@ -76,7 +76,7 @@ export interface ApiMetadataBase {
   description: string;
   source: string; // @site aliased source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md"
   sourceDirName: string; // relative to the versioned docs folder (can be ".") => "folder/subFolder/subSubFolder"
-  slug: string;
+  slug?: string;
   permalink: string;
   sidebarPosition?: number;
   frontMatter: Record<string, unknown>;