docusaurus-plugin-openapi-docs 1.0.3 → 1.0.6

package/README.md

@@ -20,6 +20,13 @@ OpenAPI plugin for generating API reference docs in Docusaurus v2.
 
 The `docusaurus-plugin-openapi-docs` package extends the Docusaurus CLI with commands for generating MDX using the OpenAPI specification as the source. The resulting MDX is fully compatible with [plugin-content-docs](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs) and can be used to render beautiful reference API docs by setting `docItemComponent` to `@theme/ApiItem`, a custom component included in the `docusaurus-theme-openapi-docs` theme.
 
+Key Features:
+
+- **Compatible:** Works with Swagger 2.0 and OpenAPI 3.x.
+- **Fast:** Convert large OpenAPI specs into MDX docs in seconds. 🔥
+- **Stylish:** Based on the same [Infima styling framework](https://infima.dev/) that powers the Docusaurus UI.
+- **Capable:** Supports single, multi and _even micro_ OpenAPI specs.
+
 ## Installation
 
 Plugin:
@@ -71,10 +78,10 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
 ],
 
   plugins: [
-    [
       'docusaurus-plugin-openapi-docs',
       {
         id: "apiDocs",
+        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
@@ -97,28 +104,53 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
 
 > Note: You may optionally configure a dedicated `@docusaurus/plugin-content-docs` instance for use with `docusaurus-theme-openapi-docs` by setting `docItemComponent` to `@theme/ApiItem`.
 
-### Plugin Configuration Options
+## Plugin Configuration Options
+
+The `docusaurus-plugin-openapi-docs` plugin can be configured with the following options:
+
+| 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
 
-`docusaurus-plugin-openapi-docs` can be configured with the following options:
+`config` can be configured with the following options:
 
-| Name             | Type     | Default | Description                                                                                                          |
-| ---------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
-| `specPath`       | `string` | `null`  | Designated path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
-| `ouputDir`       | `string` | `null`  | Desired output path for generated MDX files.                                                                         |
-| `template`       | `string` | `null`  | _Optional:_ Customize MDX content with a desired template.                                                           |
-| `sidebarOptions` | `object` | `null`  | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options.                     |
+| Name             | Type     | Default | Description                                                                                                                 |
+| ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `specPath`       | `string` | `null`  | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
+| `ouputDir`       | `string` | `null`  | Desired output path for generated MDX files.                                                                                |
+| `ouputDir`       | `string` | `null`  | Desired output path for generated MDX files.                                                                                |
+| `template`       | `string` | `null`  | _Optional:_ Customize MDX content with a desired template.                                                                  |
+| `sidebarOptions` | `object` | `null`  | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options.                            |
+| `version`        | `string` | `null`  | _Optional:_ Version assigned to single or micro-spec API specified in `specPath`.                                           |
+| `label`          | `string` | `null`  | _Optional:_ Version label used when generating version selector dropdown menu.                                              |
+| `baseUrl`        | `string` | `null`  | _Optional:_ Version base URL used when generating version selector dropdown menu.                                           |
+| `versions`       | `object` | `null`  | _Optional:_ Set of options for versioning configuration. See below for a list of supported options.                         |
 
 `sidebarOptions` can be configured with the following options:
 
 | Name                 | Type      | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | -------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `groupPathsBy`       | `string`  | `null`  | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by `tag`.                                                                                                                                                                                                                                                                                                                   |
-| `categoryLinkSource` | `string`  | `null`  | Defines what source to use for rendering category link pages when grouping paths by tag. <br/></br>The supported options are as follows: <br/></br> `tag`: Sets the category link config type to `generated-index` and uses the tag description as the link config description. <br/><br/>`info`: Sets the category link config type to `doc` and renders the `info` section as the category link (recommended only for multi/micro-spec scenarios). |
+| `categoryLinkSource` | `string`  | `null`  | Defines what source to use for rendering category link pages when grouping paths by tag. <br/><br/>The supported options are as follows: <br/><br/> `tag`: Sets the category link config type to `generated-index` and uses the tag description as the link config description. <br/><br/>`info`: Sets the category link config type to `doc` and renders the `info` section as the category link (recommended only for multi/micro-spec scenarios). |
 | `sidebarCollapsible` | `boolean` | `true`  | Whether sidebar categories are collapsible by default.                                                                                                                                                                                                                                                                                                                                                                                               |
 | `sidebarCollapsed`   | `boolean` | `true`  | Whether sidebar categories are collapsed by default.                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `customProps`        | `object`  | `null`  | Additional props for customizing a sidebar item.                                                                                                                                                                                                                                                                                                                                                                                                     |
 
-> Note: You may optionally configure a `sidebarOptions`. In doing so, an individual `sidebar.js` slice with the configured options will be generated within the respective `outputDir`.
+> You may optionally configure a `sidebarOptions`. In doing so, an individual `sidebar.js` slice with the configured options will be generated within the respective `outputDir`.
+
+`versions` can be configured with the following options:
+
+| Name       | Type     | Default | Description                                                                                                              |
+| ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `specPath` | `string` | `null`  | Designated URL or path to the source of an OpenAPI specification file or directory of micro OpenAPI specification files. |
+| `ouputDir` | `string` | `null`  | Desired output path for versioned, generated MDX files.                                                                  |
+| `label`    | `string` | `null`  | _Optional:_ Version label used when generating version selector dropdown menu.                                           |
+| `baseUrl`  | `string` | `null`  | _Optional:_ Version base URL used when generating version selector dropdown menu.                                        |
+
+> All versions will automatically inherit `sidebarOptions` from the parent/base config.
 
 ## CLI Usage
 
@@ -139,9 +171,11 @@ Commands:
   write-translations [options] [siteDir]                   Extract required translations of your site.
   write-heading-ids [options] [siteDir] [files...]         Generate heading ids in Markdown content.
   docs:version <version>                                   Tag a new docs version
-  gen-api-docs <id>                                        Generates API Docs mdx and sidebars.
-  clean-api-docs <id>                                      Clears the Generated API Docs mdx and sidebars.
-  docs:version:openapi <version>                           Tag a new docs version (openapi)
+  gen-api-docs <id>                                        Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).
+  gen-api-docs:version <id:version>                        Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).
+  clean-api-docs <id>                                      Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).
+  clean-api-docs:version <id:version>                      Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if
+                                                           enabled).
 ```
 
 ### Generating OpenAPI Docs
@@ -190,6 +224,61 @@ yarn docusaurus clean-api-docs burgers
 
 > The example above will remove all API docs relative to `burgers`.
 
+### Versioning OpenAPI docs
+
+To generate _all_ versioned OpenAPI docs, run the following command from the root directory of your project:
+
+```bash
+yarn docusaurus gen-api-docs:version <id>:all
+```
+
+Example:
+
+```bash
+yarn docusaurus gen-api-docs:version petstore:all
+```
+
+> This will generate API docs for all of the OpenAPI specification (OAS) files referenced in your `versions` config and will also generate a `versions.json` file.
+
+> Substitue `all` with a specific version ID to generate/clean a specific version. Generating for `all` or a specific version ID will automatically update the `versions.json` file.
+
+## Installing from Template
+
+Run the following to bootstrap a Docsaurus v2 site (classic theme) with `docusaurus-openapi-docs`:
+
+```bash
+npx create-docusaurus@2.0.0-beta.21 my-website --package-manager yarn
+```
+
+> When prompted to select a template choose `Git repository`.
+
+Template Repository URL:
+
+```bash
+https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs.git
+```
+
+> When asked how the template repo should be cloned choose "copy" (unless you know better).
+
+```bash
+cd my-website
+yarn
+```
+
+## Developer Quick Start
+
+> Looking to make a contribution? Make sure to checkout out our contributing guide.
+
+After [forking](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/fork) the main repository, run the following:
+
+```bash
+git clone https://github.com/<your account>/docusaurus-openapi-docs.git
+cd docusaurus-openapi-docs
+yarn
+yarn build-packages
+yarn watch:demo
+```
+
 ## Support
 
-Please read [SUPPORT.md](SUPPORT.md) for details on how to get support for this project.
+Please read [SUPPORT.md](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/SUPPORT.md) for details on how to get support for this project.

package/lib/index.d.ts

@@ -1,4 +1,9 @@
 import type { LoadContext, Plugin } from "@docusaurus/types";
 import type { PluginOptions, LoadedContent } from "./types";
 export declare function isURL(str: string): boolean;
-export default function pluginOpenAPI(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;
+export declare function getDocsData(dataArray: any[], filter: string): Object | undefined;
+declare function pluginOpenAPIDocs(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;
+declare namespace pluginOpenAPIDocs {
+    var validateOptions: ({ options, validate }: any) => any;
+}
+export default pluginOpenAPIDocs;

package/lib/index.js

@@ -9,7 +9,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isURL = void 0;
+exports.getDocsData = exports.isURL = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const utils_1 = require("@docusaurus/utils");
@@ -17,21 +17,59 @@ const chalk_1 = __importDefault(require("chalk"));
 const mustache_1 = require("mustache");
 const markdown_1 = require("./markdown");
 const openapi_1 = require("./openapi");
+const options_1 = require("./options");
 const sidebars_1 = __importDefault(require("./sidebars"));
 function isURL(str) {
     return /^(https?:)\/\//m.test(str);
 }
 exports.isURL = isURL;
-function pluginOpenAPI(context, options) {
-    let { config } = options;
-    let { siteDir } = context;
+function getDocsData(dataArray, filter) {
+    // eslint-disable-next-line array-callback-return
+    const filteredData = dataArray.filter((data) => {
+        if (data[0] === filter) {
+            return data[1];
+        }
+        // Search plugin-content-docs instances
+        if (data[0] === "@docusaurus/plugin-content-docs") {
+            const pluginId = data[1].id ? data[1].id : "default";
+            if (pluginId === filter) {
+                return data[1];
+            }
+        }
+    })[0];
+    if (filteredData) {
+        // Search presets, e.g. "classic"
+        if (filteredData[0] === filter) {
+            return filteredData[1].docs;
+        }
+        // Search plugin-content-docs instances
+        if (filteredData[0] === "@docusaurus/plugin-content-docs") {
+            const pluginId = filteredData[1].id ? filteredData[1].id : "default";
+            if (pluginId === filter) {
+                return filteredData[1];
+            }
+        }
+    }
+    return;
+}
+exports.getDocsData = getDocsData;
+function pluginOpenAPIDocs(context, 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, docsPluginId);
+    const docRouteBasePath = docData ? docData.routeBasePath : undefined;
+    const docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
     async function generateApiDocs(options) {
         let { specPath, outputDir, template, sidebarOptions } = options;
         const contentPath = isURL(specPath)
             ? 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 {
@@ -44,8 +82,7 @@ function pluginOpenAPI(context, options) {
             }
             // TODO: figure out better way to set default
             if (Object.keys(sidebarOptions !== null && sidebarOptions !== void 0 ? sidebarOptions : {}).length > 0) {
-                const sidebarSlice = (0, sidebars_1.default)(sidebarOptions, // TODO: find a better way to handle null
-                options, loadedApi, tags);
+                const sidebarSlice = (0, sidebars_1.default)(sidebarOptions, options, loadedApi, tags, docPath);
                 const sidebarSliceTemplate = template
                     ? fs_1.default.readFileSync(template).toString()
                     : `module.exports = {{{slice}}};`;
@@ -135,8 +172,14 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                 item.markdown = markdown;
                 if (item.type === "api") {
                     item.json = JSON.stringify(item.api);
+                    let infoBasePath = `${outputDir}/${item.infoId}`;
+                    if (docRouteBasePath) {
+                        infoBasePath = `${docRouteBasePath}/${outputDir
+                            .split(docPath)[1]
+                            .replace(/^\/+/g, "")}/${item.infoId}`.replace(/^\/+/g, "");
+                    }
                     if (item.infoId)
-                        item.infoPath = `${outputDir}/${item.infoId}`;
+                        item.infoPath = infoBasePath;
                 }
                 const view = (0, mustache_1.render)(mdTemplate, item);
                 const utils = (0, mustache_1.render)(infoMdTemplate, item);
@@ -192,9 +235,11 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
         const apiDir = path_1.default.join(siteDir, outputDir);
         const apiMdxFiles = await (0, utils_1.Globby)(["*.api.mdx", "*.info.mdx", "*.tag.mdx"], {
             cwd: path_1.default.resolve(apiDir),
+            deep: 1,
         });
         const sidebarFile = await (0, utils_1.Globby)(["sidebar.js"], {
             cwd: path_1.default.resolve(apiDir),
+            deep: 1,
         });
         apiMdxFiles.map((mdx) => fs_1.default.unlink(`${apiDir}/${mdx}`, (err) => {
             if (err) {
@@ -213,18 +258,48 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
             }
         }));
     }
+    async function generateVersions(versions, outputDir) {
+        let versionsArray = [];
+        for (const [version, metadata] of Object.entries(versions)) {
+            versionsArray.push({
+                version: version,
+                label: metadata.label,
+                baseUrl: metadata.baseUrl,
+            });
+        }
+        const versionsJson = JSON.stringify(versionsArray, null, 2);
+        try {
+            fs_1.default.writeFileSync(`${outputDir}/versions.json`, versionsJson, "utf8");
+            console.log(chalk_1.default.green(`Successfully created "${outputDir}/versions.json"`));
+        }
+        catch (err) {
+            console.error(chalk_1.default.red(`Failed to write "${outputDir}/versions.json"`), chalk_1.default.yellow(err));
+        }
+    }
+    async function cleanVersions(outputDir) {
+        if (fs_1.default.existsSync(`${outputDir}/versions.json`)) {
+            fs_1.default.unlink(`${outputDir}/versions.json`, (err) => {
+                if (err) {
+                    console.error(chalk_1.default.red(`Cleanup failed for "${outputDir}/versions.json"`), chalk_1.default.yellow(err));
+                }
+                else {
+                    console.log(chalk_1.default.green(`Cleanup succeeded for "${outputDir}/versions.json"`));
+                }
+            });
+        }
+    }
     return {
-        name: `docusaurus-plugin-openapi`,
+        name: `docusaurus-plugin-openapi-docs`,
         extendCli(cli) {
             cli
                 .command(`gen-api-docs`)
-                .description(`Generates API Docs mdx and sidebars.`)
-                .usage("[options] <id key value in plugin config within docusaurus.config.js>")
+                .description(`Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).`)
+                .usage("<id>")
                 .arguments("<id>")
                 .action(async (id) => {
                 if (id === "all") {
                     if (config[id]) {
-                        console.error(chalk_1.default.red("Can't use id 'all' for API Doc."));
+                        console.error(chalk_1.default.red("Can't use id 'all' for OpenAPI docs configuration key."));
                     }
                     else {
                         Object.keys(config).forEach(async function (key) {
@@ -233,21 +308,71 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                     }
                 }
                 else if (!config[id]) {
-                    console.error(chalk_1.default.red(`ID ${id} does not exist in openapi-plugin config`));
+                    console.error(chalk_1.default.red(`ID '${id}' does not exist in OpenAPI docs config.`));
                 }
                 else {
                     await generateApiDocs(config[id]);
                 }
             });
+            cli
+                .command(`gen-api-docs:version`)
+                .description(`Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).`)
+                .usage("<id:version>")
+                .arguments("<id:version>")
+                .action(async (id) => {
+                const [parentId, versionId] = id.split(":");
+                const parentConfig = Object.assign({}, config[parentId]);
+                const version = parentConfig.version;
+                const label = parentConfig.label;
+                const baseUrl = parentConfig.baseUrl;
+                let parentVersion = {};
+                parentVersion[version] = { label: label, baseUrl: baseUrl };
+                const { versions } = config[parentId];
+                const mergedVersions = Object.assign(parentVersion, versions);
+                // Prepare for merge
+                delete parentConfig.versions;
+                delete parentConfig.version;
+                delete parentConfig.label;
+                delete parentConfig.baseUrl;
+                // TODO: handle when no versions are defined by version command is passed
+                if (versionId === "all") {
+                    if (versions[id]) {
+                        console.error(chalk_1.default.red("Can't use id 'all' for OpenAPI docs versions configuration key."));
+                    }
+                    else {
+                        await generateVersions(mergedVersions, parentConfig.outputDir);
+                        Object.keys(versions).forEach(async (key) => {
+                            const versionConfig = versions[key];
+                            const mergedConfig = {
+                                ...parentConfig,
+                                ...versionConfig,
+                            };
+                            await generateApiDocs(mergedConfig);
+                        });
+                    }
+                }
+                else if (!versions[versionId]) {
+                    console.error(chalk_1.default.red(`Version ID '${versionId}' does not exist in OpenAPI docs versions config.`));
+                }
+                else {
+                    const versionConfig = versions[versionId];
+                    const mergedConfig = {
+                        ...parentConfig,
+                        ...versionConfig,
+                    };
+                    await generateVersions(mergedVersions, parentConfig.outputDir);
+                    await generateApiDocs(mergedConfig);
+                }
+            });
             cli
                 .command(`clean-api-docs`)
-                .description(`Clears the Generated API Docs mdx and sidebars.`)
-                .usage("[options] <id key value in plugin config within docusaurus.config.js>")
+                .description(`Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).`)
+                .usage("<id>")
                 .arguments("<id>")
                 .action(async (id) => {
                 if (id === "all") {
                     if (config[id]) {
-                        console.error(chalk_1.default.red("Can't use id 'all' for API Doc."));
+                        console.error(chalk_1.default.red("Can't use id 'all' for OpenAPI docs configuration key."));
                     }
                     else {
                         Object.keys(config).forEach(async function (key) {
@@ -259,7 +384,46 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                     await cleanApiDocs(config[id]);
                 }
             });
+            cli
+                .command(`clean-api-docs:version`)
+                .description(`Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if enabled).`)
+                .usage("<id:version>")
+                .arguments("<id:version>")
+                .action(async (id) => {
+                const [parentId, versionId] = id.split(":");
+                const { versions } = config[parentId];
+                const parentConfig = Object.assign({}, config[parentId]);
+                delete parentConfig.versions;
+                if (versionId === "all") {
+                    if (versions[id]) {
+                        chalk_1.default.red("Can't use id 'all' for OpenAPI docs versions configuration key.");
+                    }
+                    else {
+                        await cleanVersions(parentConfig.outputDir);
+                        Object.keys(versions).forEach(async (key) => {
+                            const versionConfig = versions[key];
+                            const mergedConfig = {
+                                ...parentConfig,
+                                ...versionConfig,
+                            };
+                            await cleanApiDocs(mergedConfig);
+                        });
+                    }
+                }
+                else {
+                    const versionConfig = versions[versionId];
+                    const mergedConfig = {
+                        ...parentConfig,
+                        ...versionConfig,
+                    };
+                    await cleanApiDocs(mergedConfig);
+                }
+            });
         },
     };
 }
-exports.default = pluginOpenAPI;
+exports.default = pluginOpenAPIDocs;
+pluginOpenAPIDocs.validateOptions = ({ options, validate }) => {
+    const validatedOptions = validate(options_1.OptionsSchema, options);
+    return validatedOptions;
+};

package/lib/markdown/createParamsDetails.js

@@ -19,6 +19,8 @@ function createParamsDetails({ parameters, type }) {
         return undefined;
     }
     return (0, createDetails_1.createDetails)({
+        "data-collapsed": false,
+        open: true,
         style: { marginBottom: "1rem" },
         children: [
             (0, createDetailsSummary_1.createDetailsSummary)({

package/lib/markdown/createSchemaDetails.js

@@ -206,6 +206,8 @@ function createSchemaDetails({ title, body, ...rest }) {
         }
     }
     return (0, createDetails_1.createDetails)({
+        "data-collapsed": false,
+        open: true,
         ...rest,
         children: [
             (0, createDetailsSummary_1.createDetailsSummary)({

package/lib/markdown/index.js

@@ -40,7 +40,7 @@ exports.createApiPageMD = createApiPageMD;
 function createInfoPageMD({ info: { title, version, description, contact, license, termsOfService }, securitySchemes, }) {
     return (0, utils_1.render)([
         `import Tabs from "@theme/Tabs";\n`,
-        `import TabItem from "@theme/TabItem";\n`,
+        `import TabItem from "@theme/TabItem";\n\n`,
         (0, createVersionBadge_1.createVersionBadge)(version),
         `# ${(0, lodash_1.escape)(title)}\n\n`,
         (0, createDescription_1.createDescription)(description),

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.d.ts

@@ -1,4 +1,2 @@
 import { Joi } from "@docusaurus/utils-validation";
-import type { PluginOptions } from "./types";
-export declare const DEFAULT_OPTIONS: PluginOptions;
 export declare const OptionsSchema: Joi.ObjectSchema<any>;