docusaurus-plugin-openapi-docs 1.0.0 → 1.0.3

package/src/openapi/createExample.ts

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import chalk from "chalk";
+
 import { SchemaObject } from "./types";
 
 interface OASTypeToTypeMap {
@@ -48,71 +50,78 @@ const primitives: Primitives = {
 };
 
 export const sampleFromSchema = (schema: SchemaObject = {}): any => {
-  let { type, example, allOf, properties, items } = schema;
+  try {
+    let { type, example, allOf, properties, items } = schema;
 
-  if (example !== undefined) {
-    return example;
-  }
+    if (example !== undefined) {
+      return example;
+    }
 
-  if (allOf) {
-    // TODO: We are just assuming it will always be an object for now
-    let obj: SchemaObject = {
-      type: "object",
-      properties: {},
-      required: [], // NOTE: We shouldn't need to worry about required
-    };
-    for (let item of allOf) {
-      if (item.properties) {
-        obj.properties = {
-          ...obj.properties,
-          ...item.properties,
-        };
+    if (allOf) {
+      // TODO: We are just assuming it will always be an object for now
+      let obj: SchemaObject = {
+        type: "object",
+        properties: {},
+        required: [], // NOTE: We shouldn't need to worry about required
+      };
+      for (let item of allOf) {
+        if (item.properties) {
+          obj.properties = {
+            ...obj.properties,
+            ...item.properties,
+          };
+        }
       }
+      return sampleFromSchema(obj);
     }
-    return sampleFromSchema(obj);
-  }
 
-  if (!type) {
-    if (properties) {
-      type = "object";
-    } else if (items) {
-      type = "array";
-    } else {
-      return;
+    if (!type) {
+      if (properties) {
+        type = "object";
+      } else if (items) {
+        type = "array";
+      } else {
+        return;
+      }
     }
-  }
 
-  if (type === "object") {
-    let obj: any = {};
-    for (let [name, prop] of Object.entries(properties ?? {})) {
-      if (prop.deprecated) {
-        continue;
+    if (type === "object") {
+      let obj: any = {};
+      for (let [name, prop] of Object.entries(properties ?? {})) {
+        if (prop.deprecated) {
+          continue;
+        }
+        obj[name] = sampleFromSchema(prop);
       }
-      obj[name] = sampleFromSchema(prop);
+      return obj;
     }
-    return obj;
-  }
 
-  if (type === "array") {
-    if (Array.isArray(items?.anyOf)) {
-      return items?.anyOf.map((item) => sampleFromSchema(item));
-    }
+    if (type === "array") {
+      if (Array.isArray(items?.anyOf)) {
+        return items?.anyOf.map((item) => sampleFromSchema(item));
+      }
 
-    if (Array.isArray(items?.oneOf)) {
-      return items?.oneOf.map((item) => sampleFromSchema(item));
-    }
+      if (Array.isArray(items?.oneOf)) {
+        return items?.oneOf.map((item) => sampleFromSchema(item));
+      }
 
-    return [sampleFromSchema(items)];
-  }
+      return [sampleFromSchema(items)];
+    }
 
-  if (schema.enum) {
-    if (schema.default) {
-      return schema.default;
+    if (schema.enum) {
+      if (schema.default) {
+        return schema.default;
+      }
+      return normalizeArray(schema.enum)[0];
     }
-    return normalizeArray(schema.enum)[0];
-  }
 
-  return primitive(schema);
+    return primitive(schema);
+  } catch (err) {
+    console.error(
+      chalk.yellow("WARNING: failed to create example from schema object:", err)
+    );
+    return;
+  }
 };
 
 function primitive(schema: SchemaObject = {}) {

package/src/openapi/openapi.test.ts

@@ -26,12 +26,6 @@ describe("openapi", () => {
       const yaml = results.find((x) => x.source.endsWith("openapi.yaml"));
       expect(yaml).toBeTruthy();
       expect(yaml?.sourceDirName).toBe(".");
-      const froyo = results.find((x) => x.source.endsWith("froyo.yaml"));
-      expect(froyo).toBeTruthy();
-      expect(froyo?.sourceDirName).toBe("yogurtstore");
-      const nested = results.find((x) => x.source.endsWith("nested.yaml"));
-      expect(nested).toBeTruthy();
-      expect(nested?.sourceDirName).toBe("yogurtstore/nested");
     });
   });
 });

package/src/openapi/openapi.ts

@@ -9,17 +9,24 @@ import path from "path";
 
 import { Globby, GlobExcludeDefault } from "@docusaurus/utils";
 import Converter from "@paloaltonetworks/openapi-to-postmanv2";
-// @ts-ignore
-import sdk, { Collection } from "@paloaltonetworks/postman-collection";
+import sdk from "@paloaltonetworks/postman-collection";
+import Collection from "@paloaltonetworks/postman-collection";
 import chalk from "chalk";
 import fs from "fs-extra";
-import yaml from "js-yaml";
 import JsonRefs from "json-refs";
 import { kebabCase } from "lodash";
 
-import { ApiMetadata, ApiPageMetadata, InfoPageMetadata } from "../types";
+import { isURL } from "../index";
+import {
+  ApiMetadata,
+  ApiPageMetadata,
+  InfoPageMetadata,
+  SidebarOptions,
+  TagPageMetadata,
+} from "../types";
 import { sampleFromSchema } from "./createExample";
 import { OpenApiObject, OpenApiObjectWithRef, TagObject } from "./types";
+import { loadAndBundleSpec } from "./utils/loadAndBundleSpec";
 
 /**
  * Finds any reference objects in the OpenAPI definition and resolves them to a finalized value.
@@ -75,22 +82,59 @@ async function createPostmanCollection(
 
 type PartialPage<T> = Omit<T, "permalink" | "source" | "sourceDirName">;
 
-function createItems(openapiData: OpenApiObject): ApiMetadata[] {
+function createItems(
+  openapiData: OpenApiObject,
+  sidebarOptions: SidebarOptions
+): ApiMetadata[] {
   // TODO: Find a better way to handle this
   let items: PartialPage<ApiMetadata>[] = [];
+  const infoId = kebabCase(openapiData.info.title);
+
+  if (sidebarOptions?.categoryLinkSource === "tag") {
+    // Only create an tag pages if categoryLinkSource set to tag.
+    const tags: TagObject[] = openapiData.tags ?? [];
+    // eslint-disable-next-line array-callback-return
+    tags
+      .filter((tag) => !tag.description?.includes("SchemaDefinition"))
+      // eslint-disable-next-line array-callback-return
+      .map((tag) => {
+        const description = getTagDisplayName(
+          tag.name!,
+          openapiData.tags ?? []
+        );
+        const tagId = kebabCase(tag.name);
+        const tagPage: PartialPage<TagPageMetadata> = {
+          type: "tag",
+          id: tagId,
+          unversionedId: tagId,
+          title: description ?? "",
+          description: description ?? "",
+          slug: "/" + tagId,
+          frontMatter: {},
+          tag: {
+            ...tag,
+          },
+        };
+        items.push(tagPage);
+      });
+  }
 
-  // Only create an info page if we have a description.
   if (openapiData.info.description) {
+    // Only create an info page if we have a description.
     const infoPage: PartialPage<InfoPageMetadata> = {
       type: "info",
-      id: "introduction",
-      unversionedId: "introduction",
-      title: "Introduction",
+      id: infoId,
+      unversionedId: infoId,
+      title: openapiData.info.title,
       description: openapiData.info.description,
-      slug: "/introduction",
+      slug: "/" + infoId,
       frontMatter: {},
+      securitySchemes: openapiData.components?.securitySchemes,
       info: {
         ...openapiData.info,
+        tags: openapiData.tags?.map((tagName) =>
+          getTagDisplayName(tagName.name!, openapiData.tags ?? [])
+        ),
         title: openapiData.info.title ?? "Introduction",
       },
     };
@@ -141,6 +185,7 @@ function createItems(openapiData: OpenApiObject): ApiMetadata[] {
       const apiPage: PartialPage<ApiPageMetadata> = {
         type: "api",
         id: baseId,
+        infoId: infoId ?? "",
         unversionedId: baseId,
         title: title,
         description: description ?? "",
@@ -175,15 +220,14 @@ function bindCollectionToApiItems(
   items: ApiMetadata[],
   postmanCollection: sdk.Collection
 ) {
-  // @ts-ignore
-  postmanCollection.forEachItem((item) => {
+  postmanCollection.forEachItem((item: any) => {
     const method = item.request.method.toLowerCase();
     const path = item.request.url
       .getPath({ unresolved: true }) // unresolved returns "/:variableName" instead of "/<type>"
       .replace(/:([a-z0-9-_]+)/gi, "{$1}"); // replace "/:variableName" with "/{variableName}"
 
     const apiItem = items.find((item) => {
-      if (item.type === "info") {
+      if (item.type === "info" || item.type === "tag") {
         return false;
       }
       return item.api.path === path && item.api.method === method;
@@ -205,36 +249,39 @@ export async function readOpenapiFiles(
   openapiPath: string,
   _options: {}
 ): Promise<OpenApiFiles[]> {
-  const stat = await fs.lstat(openapiPath);
-  if (stat.isDirectory()) {
-    console.warn(
-      chalk.yellow(
-        "WARNING: Loading a directory of OpenAPI definitions is experimental and subject to unannounced breaking changes."
-      )
-    );
-
-    // TODO: Add config for inlcude/ignore
-    const allFiles = await Globby(["**/*.{json,yaml,yml}"], {
-      cwd: openapiPath,
-      ignore: GlobExcludeDefault,
-    });
-    const sources = allFiles.filter((x) => !x.includes("_category_")); // todo: regex exclude?
-    return Promise.all(
-      sources.map(async (source) => {
-        // TODO: make a function for this
-        const fullPath = path.join(openapiPath, source);
-        const openapiString = await fs.readFile(fullPath, "utf-8");
-        const data = yaml.load(openapiString) as OpenApiObjectWithRef;
-        return {
-          source: fullPath, // This will be aliased in process.
-          sourceDirName: path.dirname(source),
-          data,
-        };
-      })
-    );
+  if (!isURL(openapiPath)) {
+    const stat = await fs.lstat(openapiPath);
+    if (stat.isDirectory()) {
+      console.warn(
+        chalk.yellow(
+          "WARNING: Loading a directory of OpenAPI definitions is experimental and subject to unannounced breaking changes."
+        )
+      );
+
+      // TODO: Add config for inlcude/ignore
+      const allFiles = await Globby(["**/*.{json,yaml,yml}"], {
+        cwd: openapiPath,
+        ignore: GlobExcludeDefault,
+        deep: 1,
+      });
+      const sources = allFiles.filter((x) => !x.includes("_category_")); // todo: regex exclude?
+      return Promise.all(
+        sources.map(async (source) => {
+          // TODO: make a function for this
+          const fullPath = path.join(openapiPath, source);
+          const data = (await loadAndBundleSpec(
+            fullPath
+          )) as OpenApiObjectWithRef;
+          return {
+            source: fullPath, // This will be aliased in process.
+            sourceDirName: path.dirname(source),
+            data,
+          };
+        })
+      );
+    }
   }
-  const openapiString = await fs.readFile(openapiPath, "utf-8");
-  const data = yaml.load(openapiString) as OpenApiObjectWithRef;
+  const data = (await loadAndBundleSpec(openapiPath)) as OpenApiObjectWithRef;
   return [
     {
       source: openapiPath, // This will be aliased in process.
@@ -245,35 +292,50 @@ export async function readOpenapiFiles(
 }
 
 export async function processOpenapiFiles(
-  files: OpenApiFiles[]
-): Promise<ApiMetadata[]> {
+  files: OpenApiFiles[],
+  sidebarOptions: SidebarOptions
+): Promise<[ApiMetadata[], TagObject[]]> {
   const promises = files.map(async (file) => {
-    const items = await processOpenapiFile(file.data);
-    return items.map((item) => ({
+    const processedFile = await processOpenapiFile(file.data, sidebarOptions);
+    const itemsObjectsArray = processedFile[0].map((item) => ({
       ...item,
     }));
+    const tags = processedFile[1];
+    return [itemsObjectsArray, tags];
   });
   const metadata = await Promise.all(promises);
-  const items = metadata.flat();
-  return items;
+  const items = metadata
+    .map(function (x) {
+      return x[0];
+    })
+    .flat();
+  const tags = metadata.map(function (x) {
+    return x[1];
+  });
+  return [items as ApiMetadata[], tags as TagObject[]];
 }
 
 export async function processOpenapiFile(
-  openapiDataWithRefs: OpenApiObjectWithRef
-): Promise<ApiMetadata[]> {
+  openapiDataWithRefs: OpenApiObjectWithRef,
+  sidebarOptions: SidebarOptions
+): Promise<[ApiMetadata[], TagObject[]]> {
   const openapiData = await resolveRefs(openapiDataWithRefs);
   const postmanCollection = await createPostmanCollection(openapiData);
-  const items = createItems(openapiData);
+  const items = createItems(openapiData, sidebarOptions);
 
   bindCollectionToApiItems(items, postmanCollection);
 
-  return items;
+  let tags: TagObject[] = [];
+  if (openapiData.tags !== undefined) {
+    tags = openapiData.tags;
+  }
+  return [items, tags];
 }
 
 // order for picking items as a display name of tags
 const tagDisplayNameProperties = ["x-displayName", "name"] as const;
 
-function getTagDisplayName(tagName: string, tags: TagObject[]): string {
+export function getTagDisplayName(tagName: string, tags: TagObject[]): string {
   // find the very own tagObject
   const tagObject = tags.find((tagObject) => tagObject.name === tagName) ?? {
     // if none found, just fake one

package/src/openapi/types.ts

@@ -40,6 +40,7 @@ export interface InfoObject {
   contact?: ContactObject;
   license?: LicenseObject;
   version: string;
+  tags?: String[];
 }
 
 export interface ContactObject {
@@ -182,6 +183,7 @@ export interface ParameterObject {
   examples?: Map<ExampleObject>;
   //
   content?: Map<MediaTypeObject>;
+  param?: Object;
   // ignoring stylings: matrix, label, form, simple, spaceDelimited,
   // pipeDelimited and deepObject
 }
@@ -293,7 +295,7 @@ export type HeaderObject = Omit<ParameterObject, "name" | "in">;
 export type HeaderObjectWithRef = Omit<ParameterObjectWithRef, "name" | "in">;
 
 export interface TagObject {
-  name: string;
+  name?: string;
   description?: string;
   externalDocs?: ExternalDocumentationObject;
   "x-displayName"?: string;
@@ -399,6 +401,8 @@ export interface HttpSecuritySchemeObject {
   description?: string;
   scheme: string;
   bearerFormat?: string;
+  name?: string;
+  in?: string;
 }
 
 export interface Oauth2SecuritySchemeObject {

package/src/openapi/utils/loadAndBundleSpec.ts

@@ -0,0 +1,62 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+// @ts-nocheck
+
+import type { Source, Document } from "@redocly/openapi-core";
+import { bundle } from "@redocly/openapi-core/lib/bundle";
+import type { ResolvedConfig } from "@redocly/openapi-core/lib/config";
+import { Config } from "@redocly/openapi-core/lib/config/config";
+import { convertObj } from "swagger2openapi";
+
+import { OpenAPISpec } from "./types";
+
+export async function loadAndBundleSpec(
+  specUrlOrObject: object | string
+): Promise<OpenAPISpec> {
+  const config = new Config({} as ResolvedConfig);
+  const bundleOpts = {
+    config,
+    base: process.cwd(),
+  };
+
+  if (typeof specUrlOrObject === "object" && specUrlOrObject !== null) {
+    bundleOpts["doc"] = {
+      source: { absoluteRef: "" } as Source,
+      parsed: specUrlOrObject,
+    } as Document;
+  } else {
+    bundleOpts["ref"] = specUrlOrObject;
+  }
+
+  // Force dereference ?
+  // bundleOpts["dereference"] = true;
+
+  const {
+    bundle: { parsed },
+  } = await bundle(bundleOpts);
+  return parsed.swagger !== undefined ? convertSwagger2OpenAPI(parsed) : parsed;
+}
+
+export function convertSwagger2OpenAPI(spec: any): Promise<OpenAPISpec> {
+  console.warn(
+    "[ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0"
+  );
+  return new Promise<OpenAPISpec>((resolve, reject) =>
+    convertObj(
+      spec,
+      { patch: true, warnOnly: true, text: "{}", anchors: true },
+      (err, res) => {
+        // TODO: log any warnings
+        if (err) {
+          return reject(err);
+        }
+        resolve(res && (res.openapi as any));
+      }
+    )
+  );
+}