docusaurus-plugin-openapi-docs 1.0.5 → 1.0.6

package/README.md

@@ -81,7 +81,7 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
       'docusaurus-plugin-openapi-docs',
       {
         id: "apiDocs",
-        docPluginId: "classic",
+        docsPluginId: "classic",
         config: {
           petstore: { // Note: petstore key is treated as the <id> and can be used to specify an API doc instance when using CLI commands
             specPath: "examples/petstore.yaml", // Path to designated spec file
@@ -108,10 +108,10 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
 
 The `docusaurus-plugin-openapi-docs` plugin can be configured with the following options:
 
-| Name          | Type     | Default | Description                                                                                                                                          |
-| ------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`          | `string` | `null`  | A unique document id.                                                                                                                                |
-| `docPluginId` | `string` | `null`  | The ID associated with the `plugin-content-docs` or `preset` instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default"). |
+| Name           | Type     | Default | Description                                                                                                                                          |
+| -------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`           | `string` | `null`  | A unique document id.                                                                                                                                |
+| `docsPluginId` | `string` | `null`  | The ID associated with the `plugin-content-docs` or `preset` instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default"). |
 
 ### config
 

package/lib/index.js

@@ -54,13 +54,13 @@ function getDocsData(dataArray, filter) {
 }
 exports.getDocsData = getDocsData;
 function pluginOpenAPIDocs(context, options) {
-    const { config, docPluginId } = options;
+    const { config, docsPluginId } = options;
     const { siteDir, siteConfig } = context;
     // Get routeBasePath and path from plugin-content-docs or preset
     const presets = siteConfig.presets;
     const plugins = siteConfig.plugins;
     const presetsPlugins = presets.concat(plugins);
-    const docData = getDocsData(presetsPlugins, docPluginId);
+    const docData = getDocsData(presetsPlugins, docsPluginId);
     const docRouteBasePath = docData ? docData.routeBasePath : undefined;
     const docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
     async function generateApiDocs(options) {
@@ -69,7 +69,7 @@ function pluginOpenAPIDocs(context, options) {
             ? specPath
             : path_1.default.resolve(siteDir, specPath);
         try {
-            const openapiFiles = await (0, openapi_1.readOpenapiFiles)(contentPath, {});
+            const openapiFiles = await (0, openapi_1.readOpenapiFiles)(contentPath, options);
             const [loadedApi, tags] = await (0, openapi_1.processOpenapiFiles)(openapiFiles, sidebarOptions);
             if (!fs_1.default.existsSync(outputDir)) {
                 try {

package/lib/openapi/openapi.d.ts

@@ -1,11 +1,11 @@
-import { ApiMetadata, SidebarOptions } from "../types";
+import { ApiMetadata, APIOptions, SidebarOptions } from "../types";
 import { OpenApiObjectWithRef, TagObject } from "./types";
 interface OpenApiFiles {
     source: string;
     sourceDirName: string;
     data: OpenApiObjectWithRef;
 }
-export declare function readOpenapiFiles(openapiPath: string, _options: {}): Promise<OpenApiFiles[]>;
+export declare function readOpenapiFiles(openapiPath: string, options: APIOptions): Promise<OpenApiFiles[]>;
 export declare function processOpenapiFiles(files: OpenApiFiles[], sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[]]>;
 export declare function processOpenapiFile(openapiDataWithRefs: OpenApiObjectWithRef, sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[]]>;
 export declare function getTagDisplayName(tagName: string, tags: TagObject[]): string;

package/lib/openapi/openapi.js

@@ -188,7 +188,10 @@ function bindCollectionToApiItems(items, postmanCollection) {
         }
     });
 }
-async function readOpenapiFiles(openapiPath, _options) {
+async function readOpenapiFiles(openapiPath, options) {
+    // TODO: determine if this should be an API option
+    // Forces the json-schema-ref-parser
+    const parseJsonRefs = true;
     if (!(0, index_1.isURL)(openapiPath)) {
         const stat = await fs_extra_1.default.lstat(openapiPath);
         if (stat.isDirectory()) {
@@ -203,7 +206,7 @@ async function readOpenapiFiles(openapiPath, _options) {
             return Promise.all(sources.map(async (source) => {
                 // TODO: make a function for this
                 const fullPath = path_1.default.join(openapiPath, source);
-                const data = (await (0, loadAndBundleSpec_1.loadAndBundleSpec)(fullPath));
+                const data = (await (0, loadAndBundleSpec_1.loadAndBundleSpec)(fullPath, parseJsonRefs));
                 return {
                     source: fullPath,
                     sourceDirName: path_1.default.dirname(source),
@@ -212,7 +215,7 @@ async function readOpenapiFiles(openapiPath, _options) {
             }));
         }
     }
-    const data = (await (0, loadAndBundleSpec_1.loadAndBundleSpec)(openapiPath));
+    const data = (await (0, loadAndBundleSpec_1.loadAndBundleSpec)(openapiPath, parseJsonRefs));
     return [
         {
             source: openapiPath,

package/lib/openapi/openapi.test.js

@@ -15,7 +15,7 @@ const _1 = require(".");
 describe("openapi", () => {
     describe("readOpenapiFiles", () => {
         it("readOpenapiFiles", async () => {
-            const results = await (0, _1.readOpenapiFiles)(path_1.default.join(__dirname, "__fixtures__/examples"), {});
+            const results = await (0, _1.readOpenapiFiles)(path_1.default.join(__dirname, "__fixtures__/examples"), { specPath: "./", outputDir: "./" });
             const categoryMeta = results.find((x) => x.source.endsWith("_category_.json"));
             expect(categoryMeta).toBeFalsy();
             // console.log(results);

package/lib/openapi/utils/loadAndBundleSpec.d.ts

@@ -1,3 +1,3 @@
 import { OpenAPISpec } from "./types";
-export declare function loadAndBundleSpec(specUrlOrObject: object | string): Promise<OpenAPISpec>;
+export declare function loadAndBundleSpec(specUrlOrObject: object | string, parseJsonRefs: boolean | undefined): Promise<OpenAPISpec>;
 export declare function convertSwagger2OpenAPI(spec: any): Promise<OpenAPISpec>;

package/lib/openapi/utils/loadAndBundleSpec.js

@@ -5,12 +5,39 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertSwagger2OpenAPI = exports.loadAndBundleSpec = void 0;
+// @ts-nocheck
+const json_schema_ref_parser_1 = __importDefault(require("@apidevtools/json-schema-ref-parser"));
 const bundle_1 = require("@redocly/openapi-core/lib/bundle");
 const config_1 = require("@redocly/openapi-core/lib/config/config");
+const chalk_1 = __importDefault(require("chalk"));
 const swagger2openapi_1 = require("swagger2openapi");
-async function loadAndBundleSpec(specUrlOrObject) {
+async function resolveJsonRefs(specUrlOrObject) {
+    var _a, _b;
+    try {
+        let schema = await json_schema_ref_parser_1.default.dereference(specUrlOrObject, {
+            continueOnError: true,
+            resolve: {
+                http: {
+                    timeout: 15000, // 15 sec timeout
+                },
+            },
+            dereference: {
+                circular: "ignore",
+            },
+        });
+        return schema;
+    }
+    catch (err) {
+        console.error(chalk_1.default.yellow((_b = (_a = err.errors[0]) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : err));
+        return;
+    }
+}
+async function loadAndBundleSpec(specUrlOrObject, parseJsonRefs) {
     const config = new config_1.Config({});
     const bundleOpts = {
         config,
@@ -28,6 +55,14 @@ async function loadAndBundleSpec(specUrlOrObject) {
     // Force dereference ?
     // bundleOpts["dereference"] = true;
     const { bundle: { parsed }, } = await (0, bundle_1.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;
 }
 exports.loadAndBundleSpec = loadAndBundleSpec;

package/lib/options.js

@@ -17,7 +17,7 @@ const sidebarOptions = utils_validation_1.Joi.object({
 });
 exports.OptionsSchema = utils_validation_1.Joi.object({
     id: utils_validation_1.Joi.string().required(),
-    docPluginId: utils_validation_1.Joi.string().required(),
+    docsPluginId: utils_validation_1.Joi.string().required(),
     config: utils_validation_1.Joi.object()
         .pattern(/^/, utils_validation_1.Joi.object({
         specPath: utils_validation_1.Joi.string().required(),

package/lib/sidebars/index.js

@@ -19,7 +19,7 @@ function isInfoItem(item) {
     return item.type === "info";
 }
 function groupByTags(items, sidebarOptions, options, tags, docPath) {
-    const { outputDir } = options;
+    const { outputDir, label } = options;
     const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, } = sidebarOptions;
     const apiItems = items.filter(isApiItem);
     const infoItems = items.filter(isInfoItem);
@@ -95,7 +95,9 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
             linkConfig = {
                 type: "generated-index",
                 title: tag,
-                slug: "/category/" + (0, lodash_1.kebabCase)(tag),
+                slug: label
+                    ? "/category/" + (0, lodash_1.kebabCase)(label) + "/" + (0, lodash_1.kebabCase)(tag)
+                    : "/category/" + (0, lodash_1.kebabCase)(tag),
             };
         }
         return {

package/lib/types.d.ts

@@ -3,7 +3,7 @@ import { InfoObject, OperationObject, SecuritySchemeObject, TagObject } from "./
 export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs-types";
 export interface PluginOptions {
     id?: string;
-    docPluginId: string;
+    docsPluginId: string;
     config: {
         [key: string]: APIOptions;
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -36,6 +36,7 @@
     "utility-types": "^3.10.0"
   },
   "dependencies": {
+    "@apidevtools/json-schema-ref-parser": "^9.0.9",
     "@docusaurus/mdx-loader": "2.0.0-beta.21",
     "@docusaurus/plugin-content-docs": "2.0.0-beta.21",
     "@docusaurus/utils": "2.0.0-beta.21",
@@ -62,5 +63,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "fe58997d349cdab4f113c4a7449cd650882dcab6"
+  "gitHead": "ff7622e334e96e7f39b0daf5ef2cb17bfa832834"
 }

package/src/index.ts

@@ -62,14 +62,14 @@ export default function pluginOpenAPIDocs(
   context: LoadContext,
   options: PluginOptions
 ): Plugin<LoadedContent> {
-  const { config, docPluginId } = options;
+  const { config, docsPluginId } = options;
   const { siteDir, siteConfig } = context;
 
   // Get routeBasePath and path from plugin-content-docs or preset
   const presets: any = siteConfig.presets;
   const plugins: any = siteConfig.plugins;
   const presetsPlugins = presets.concat(plugins);
-  const docData: any = getDocsData(presetsPlugins, docPluginId);
+  const docData: any = getDocsData(presetsPlugins, docsPluginId);
   const docRouteBasePath = docData ? docData.routeBasePath : undefined;
   const docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
 
@@ -81,7 +81,7 @@ export default function pluginOpenAPIDocs(
       : path.resolve(siteDir, specPath);
 
     try {
-      const openapiFiles = await readOpenapiFiles(contentPath, {});
+      const openapiFiles = await readOpenapiFiles(contentPath, options);
       const [loadedApi, tags] = await processOpenapiFiles(
         openapiFiles,
         sidebarOptions!

package/src/openapi/openapi.test.ts

@@ -16,7 +16,7 @@ describe("openapi", () => {
     it("readOpenapiFiles", async () => {
       const results = await readOpenapiFiles(
         path.join(__dirname, "__fixtures__/examples"),
-        {}
+        { specPath: "./", outputDir: "./" }
       );
       const categoryMeta = results.find((x) =>
         x.source.endsWith("_category_.json")

package/src/openapi/openapi.ts

@@ -19,6 +19,7 @@ import { kebabCase } from "lodash";
 import { isURL } from "../index";
 import {
   ApiMetadata,
+  APIOptions,
   ApiPageMetadata,
   InfoPageMetadata,
   SidebarOptions,
@@ -247,8 +248,12 @@ interface OpenApiFiles {
 
 export async function readOpenapiFiles(
   openapiPath: string,
-  _options: {}
+  options: APIOptions
 ): Promise<OpenApiFiles[]> {
+  // TODO: determine if this should be an API option
+  // Forces the json-schema-ref-parser
+  const parseJsonRefs = true;
+
   if (!isURL(openapiPath)) {
     const stat = await fs.lstat(openapiPath);
     if (stat.isDirectory()) {
@@ -270,7 +275,8 @@ export async function readOpenapiFiles(
           // TODO: make a function for this
           const fullPath = path.join(openapiPath, source);
           const data = (await loadAndBundleSpec(
-            fullPath
+            fullPath,
+            parseJsonRefs
           )) as OpenApiObjectWithRef;
           return {
             source: fullPath, // This will be aliased in process.
@@ -281,7 +287,10 @@ export async function readOpenapiFiles(
       );
     }
   }
-  const data = (await loadAndBundleSpec(openapiPath)) as OpenApiObjectWithRef;
+  const data = (await loadAndBundleSpec(
+    openapiPath,
+    parseJsonRefs
+  )) as OpenApiObjectWithRef;
   return [
     {
       source: openapiPath, // This will be aliased in process.

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

@@ -17,7 +17,7 @@ const sidebarOptions = Joi.object({
 
 export const OptionsSchema = Joi.object({
   id: Joi.string().required(),
-  docPluginId: Joi.string().required(),
+  docsPluginId: Joi.string().required(),
   config: Joi.object()
     .pattern(
       /^/,

package/src/sidebars/index.ts

@@ -38,7 +38,7 @@ function groupByTags(
   tags: TagObject[],
   docPath: string
 ): ProcessedSidebar {
-  const { outputDir } = options;
+  const { outputDir, label } = options;
   const {
     sidebarCollapsed,
     sidebarCollapsible,
@@ -135,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;
       }
 

package/src/types.ts

@@ -22,7 +22,7 @@ export type {
 } from "@docusaurus/plugin-content-docs-types";
 export interface PluginOptions {
   id?: string;
-  docPluginId: string;
+  docsPluginId: string;
   config: {
     [key: string]: APIOptions;
   };