docusaurus-plugin-openapi-docs 1.0.3 → 1.0.6

package/src/openapi/utils/loadAndBundleSpec.ts

@@ -7,16 +7,39 @@
 
 // @ts-nocheck
 
+import $RefParser from "@apidevtools/json-schema-ref-parser";
 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 chalk from "chalk";
 import { convertObj } from "swagger2openapi";
 
 import { OpenAPISpec } from "./types";
 
+async function resolveJsonRefs(specUrlOrObject: object | string) {
+  try {
+    let schema = await $RefParser.dereference(specUrlOrObject, {
+      continueOnError: true,
+      resolve: {
+        http: {
+          timeout: 15000, // 15 sec timeout
+        },
+      },
+      dereference: {
+        circular: "ignore",
+      },
+    });
+    return schema;
+  } catch (err) {
+    console.error(chalk.yellow(err.errors[0]?.message ?? err));
+    return;
+  }
+}
+
 export async function loadAndBundleSpec(
-  specUrlOrObject: object | string
+  specUrlOrObject: object | string,
+  parseJsonRefs: boolean | undefined
 ): Promise<OpenAPISpec> {
   const config = new Config({} as ResolvedConfig);
   const bundleOpts = {
@@ -39,6 +62,14 @@ export async function loadAndBundleSpec(
   const {
     bundle: { parsed },
   } = await bundle(bundleOpts);
+  if (parseJsonRefs) {
+    const resolved = resolveJsonRefs(parsed);
+    return typeof resolved === Object
+      ? resolved.swagger !== undefined
+        ? convertSwagger2OpenAPI(resolved)
+        : resolved
+      : parsed;
+  }
   return parsed.swagger !== undefined ? convertSwagger2OpenAPI(parsed) : parsed;
 }
 

package/src/options.ts

@@ -7,14 +7,47 @@
 
 import { Joi } from "@docusaurus/utils-validation";
 
-import type { PluginOptions } from "./types";
-
-export const DEFAULT_OPTIONS: PluginOptions = {
-  id: "default",
-  config: {},
-};
+const sidebarOptions = Joi.object({
+  groupPathsBy: Joi.string().valid("tag"),
+  categoryLinkSource: Joi.string().valid("tag", "info"),
+  customProps: Joi.object(),
+  sidebarCollapsible: Joi.boolean(),
+  sidebarCollapsed: Joi.boolean(),
+});
 
 export const OptionsSchema = Joi.object({
-  id: Joi.string().default(DEFAULT_OPTIONS.id),
-  config: Joi.object().default(DEFAULT_OPTIONS.config),
+  id: Joi.string().required(),
+  docsPluginId: Joi.string().required(),
+  config: Joi.object()
+    .pattern(
+      /^/,
+      Joi.object({
+        specPath: Joi.string().required(),
+        outputDir: Joi.string().required(),
+        template: Joi.string(),
+        sidebarOptions: sidebarOptions,
+        version: Joi.string().when("versions", {
+          is: Joi.exist(),
+          then: Joi.required(),
+        }),
+        label: Joi.string().when("versions", {
+          is: Joi.exist(),
+          then: Joi.required(),
+        }),
+        baseUrl: Joi.string().when("versions", {
+          is: Joi.exist(),
+          then: Joi.required(),
+        }),
+        versions: Joi.object().pattern(
+          /^/,
+          Joi.object({
+            specPath: Joi.string().required(),
+            outputDir: Joi.string().required(),
+            label: Joi.string().required(),
+            baseUrl: Joi.string().required(),
+          })
+        ),
+      })
+    )
+    .required(),
 });

package/src/sidebars/index.ts

@@ -35,9 +35,10 @@ function groupByTags(
   items: ApiPageMetadata[],
   sidebarOptions: SidebarOptions,
   options: APIOptions,
-  tags: TagObject[]
+  tags: TagObject[],
+  docPath: string
 ): ProcessedSidebar {
-  const { outputDir } = options;
+  const { outputDir, label } = options;
   const {
     sidebarCollapsed,
     sidebarCollapsible,
@@ -63,10 +64,9 @@ function groupByTags(
       .filter((item): item is string => !!item)
   );
 
-  // TODO: optimize this or make it a function
-  const basePath = outputDir
-    .slice(outputDir.indexOf("/", 1))
-    .replace(/^\/+/g, "");
+  const basePath = docPath
+    ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
+    : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
 
   function createDocItem(item: ApiPageMetadata): SidebarItemDoc {
     const sidebar_label = item.frontMatter.sidebar_label;
@@ -74,7 +74,8 @@ function groupByTags(
     const id = item.id;
     return {
       type: "doc" as const,
-      id: `${basePath}/${item.id}`,
+      id:
+        basePath === "" || undefined ? `${item.id}` : `${basePath}/${item.id}`,
       label: (sidebar_label as string) ?? title ?? id,
       customProps: customProps,
       className: clsx(
@@ -134,7 +135,9 @@ function groupByTags(
         linkConfig = {
           type: "generated-index" as "generated-index",
           title: tag,
-          slug: "/category/" + kebabCase(tag),
+          slug: label
+            ? "/category/" + kebabCase(label) + "/" + kebabCase(tag)
+            : "/category/" + kebabCase(tag),
         } as SidebarItemCategoryLinkConfig;
       }
 
@@ -183,7 +186,8 @@ export default function generateSidebarSlice(
   sidebarOptions: SidebarOptions,
   options: APIOptions,
   api: ApiMetadata[],
-  tags: TagObject[]
+  tags: TagObject[],
+  docPath: string
 ) {
   let sidebarSlice: ProcessedSidebar = [];
   if (sidebarOptions.groupPathsBy === "tag") {
@@ -191,7 +195,8 @@ export default function generateSidebarSlice(
       api as ApiPageMetadata[],
       sidebarOptions,
       options,
-      tags
+      tags,
+      docPath
     );
   }
   return sidebarSlice;

package/src/sidebars/utils.ts

@@ -0,0 +1,29 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+import { render } from "mustache";
+
+export function versionSelector(versions: object[]) {
+  const template = `<div class="dropdown dropdown--hoverable dropdown--right">
+  <button class="button button--block button--sm button--secondary"><span>Select API Version</span></button>
+  <ul class="dropdown__menu">
+    {{#.}}<li><a class="dropdown__link" href="{{{baseUrl}}}">{{{label}}}</a></li>{{/.}}
+  </ul>
+</div>
+      `;
+  const view = render(template, versions);
+  return view;
+}
+
+export function versionCrumb(version: string) {
+  const template = `<ul style="display: flex;" class="breadcrumbs breadcrumbs--sm">
+  <li style="margin-left: auto; margin-right: 0;" class="breadcrumbs__item breadcrumbs__item--active">
+  <a class="breadcrumbs__link"><span>{{{.}}}</span></a></li></ul>
+      `;
+  const view = render(template, version);
+  return view;
+}

package/src/types.ts

@@ -22,6 +22,7 @@ export type {
 } from "@docusaurus/plugin-content-docs-types";
 export interface PluginOptions {
   id?: string;
+  docsPluginId: string;
   config: {
     [key: string]: APIOptions;
   };
@@ -32,6 +33,27 @@ export interface APIOptions {
   outputDir: string;
   template?: string;
   sidebarOptions?: SidebarOptions;
+  version?: string;
+  label?: string;
+  baseUrl?: string;
+  versions?: {
+    [key: string]: APIVersionOptions;
+  };
+}
+
+export interface SidebarOptions {
+  groupPathsBy?: string;
+  categoryLinkSource?: string;
+  customProps?: { [key: string]: unknown };
+  sidebarCollapsible?: boolean;
+  sidebarCollapsed?: boolean;
+}
+
+export interface APIVersionOptions {
+  specPath: string;
+  outputDir: string;
+  label: string;
+  baseUrl: string;
 }
 
 export interface LoadedContent {
@@ -99,11 +121,3 @@ export interface ApiNavLink {
   title: string;
   permalink: string;
 }
-
-export interface SidebarOptions {
-  groupPathsBy?: string;
-  categoryLinkSource?: string;
-  customProps?: { [key: string]: unknown };
-  sidebarCollapsible?: boolean;
-  sidebarCollapsed?: boolean;
-}