docusaurus-plugin-openapi-docs 1.3.2 → 1.4.1

package/README.md

@@ -122,6 +122,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 | `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.                                                                                |
 | `template`       | `string` | `null`  | _Optional:_ Customize MDX content with a desired template.                                                                  |
+| `downloadUrl`    | `string` | `null`  | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc)                             |
 | `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.                                              |

package/lib/index.js

@@ -73,7 +73,7 @@ function pluginOpenAPIDocs(context, options) {
     let docRouteBasePath = docData ? docData.routeBasePath : undefined;
     let docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
     async function generateApiDocs(options, pluginId) {
-        let { specPath, outputDir, template, sidebarOptions } = options;
+        let { specPath, outputDir, template, downloadUrl, sidebarOptions } = options;
         // Override docPath if pluginId provided
         if (pluginId) {
             docData = getDocsPluginConfig(presetsPlugins, pluginId);
@@ -179,6 +179,11 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 \`\`\`
       `;
             loadedApi.map(async (item) => {
+                if (item.type === "info") {
+                    if (downloadUrl && isURL(downloadUrl)) {
+                        item.downloadUrl = downloadUrl;
+                    }
+                }
                 const markdown = item.type === "api"
                     ? (0, markdown_1.createApiPageMD)(item)
                     : item.type === "info"

package/lib/markdown/createDownload.d.ts

@@ -0,0 +1 @@
+export declare function createDownload(url: string | undefined): string;

package/lib/markdown/createDownload.js

@@ -0,0 +1,17 @@
+"use strict";
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDownload = void 0;
+const utils_1 = require("./utils");
+function createDownload(url) {
+    return (0, utils_1.guard)(url, (url) => [
+        (0, utils_1.create)("Export", { url: url, proxy: undefined }),
+        `\n\n`,
+    ]);
+}
+exports.createDownload = createDownload;

package/lib/markdown/createResponseSchema.js

@@ -586,7 +586,8 @@ function createResponseSchema({ title, body, ...rest }) {
                     value: `${mimeType}`,
                     children: [
                         (0, utils_1.create)("SchemaTabs", {
-                            groupId: "schema-tabs",
+                            // TODO: determine if we should persist this
+                            // groupId: "schema-tabs",
                             children: [
                                 firstBody &&
                                     (0, utils_1.create)("TabItem", {

package/lib/markdown/index.d.ts

@@ -1,4 +1,4 @@
 import { ApiPageMetadata, InfoPageMetadata, TagPageMetadata } from "../types";
 export declare function createApiPageMD({ title, api: { deprecated, "x-deprecated-description": deprecatedDescription, description, parameters, requestBody, responses, }, }: ApiPageMetadata): string;
-export declare function createInfoPageMD({ info: { title, version, description, contact, license, termsOfService, logo, darkLogo, }, securitySchemes, }: InfoPageMetadata): string;
+export declare function createInfoPageMD({ info: { title, version, description, contact, license, termsOfService, logo, darkLogo, }, securitySchemes, downloadUrl, }: InfoPageMetadata): string;
 export declare function createTagPageMD({ tag: { description } }: TagPageMetadata): string;

package/lib/markdown/index.js

@@ -11,6 +11,7 @@ const createAuthentication_1 = require("./createAuthentication");
 const createContactInfo_1 = require("./createContactInfo");
 const createDeprecationNotice_1 = require("./createDeprecationNotice");
 const createDescription_1 = require("./createDescription");
+const createDownload_1 = require("./createDownload");
 const createLicense_1 = require("./createLicense");
 const createLogo_1 = require("./createLogo");
 const createParamsDetails_1 = require("./createParamsDetails");
@@ -44,12 +45,14 @@ function createApiPageMD({ title, api: { deprecated, "x-deprecated-description":
     ]);
 }
 exports.createApiPageMD = createApiPageMD;
-function createInfoPageMD({ info: { title, version, description, contact, license, termsOfService, logo, darkLogo, }, securitySchemes, }) {
+function createInfoPageMD({ info: { title, version, description, contact, license, termsOfService, logo, darkLogo, }, securitySchemes, downloadUrl, }) {
     return (0, utils_1.render)([
         `import ApiLogo from "@theme/ApiLogo";\n`,
         `import Tabs from "@theme/Tabs";\n`,
-        `import TabItem from "@theme/TabItem";\n\n`,
+        `import TabItem from "@theme/TabItem";\n`,
+        `import Export from "@theme/ApiDemoPanel/Export";\n\n`,
         (0, createVersionBadge_1.createVersionBadge)(version),
+        (0, createDownload_1.createDownload)(downloadUrl),
         `# ${title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")}\n\n`,
         (0, createLogo_1.createLogo)(logo, darkLogo),
         (0, createDescription_1.createDescription)(description),

package/lib/markdown/utils.js

@@ -35,5 +35,5 @@ function render(children) {
 }
 exports.render = render;
 // Regex to selectively URL-encode '>' and '<' chars
-exports.lessThan = /<(?!(button|\s?\/button|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|a|\s?\/a|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|div|\s?\/div|center|\s?\/center))/giu;
-exports.greaterThan = /(?<!(button|details|summary|hr|br|span|strong|small|table|td|tr|th|h1|h2|h3|h4|h5|h6|title|p|em|b|i|u|strike|a|tag|li|ol|ul|img|div|center|\/|\s|"|'))>/giu;
+exports.lessThan = /<(?!(=|button|\s?\/button|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|a|\s?\/a|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|div|\s?\/div|center|\s?\/center))/giu;
+exports.greaterThan = /(?<!(button|details|summary|hr|br|span|strong|small|table|td|tr|th|h1|h2|h3|h4|h5|h6|title|p|em|b|i|u|strike|a|tag|li|ol|ul|img|div|center|\/|\s|"|'))>?!=/giu;

package/lib/options.js

@@ -23,6 +23,7 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
         specPath: utils_validation_1.Joi.string().required(),
         outputDir: utils_validation_1.Joi.string().required(),
         template: utils_validation_1.Joi.string(),
+        downloadUrl: utils_validation_1.Joi.string(),
         sidebarOptions: sidebarOptions,
         version: utils_validation_1.Joi.string().when("versions", {
             is: utils_validation_1.Joi.exist(),

package/lib/types.d.ts

@@ -12,6 +12,7 @@ export interface APIOptions {
     specPath: string;
     outputDir: string;
     template?: string;
+    downloadUrl?: string;
     sidebarOptions?: SidebarOptions;
     version?: string;
     label?: string;
@@ -47,6 +48,7 @@ export interface ApiMetadataBase {
     unversionedId: string;
     infoId?: string;
     infoPath?: string;
+    downloadUrl?: string;
     title: string;
     description: string;
     source: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.3.2",
+  "version": "1.4.1",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -68,5 +68,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "761a89172da04573369441cf7342f6c643bc3ecd"
+  "gitHead": "ddfa49093f75f628536b8d9e25f88eb9e541667c"
 }

package/src/index.ts

@@ -85,7 +85,8 @@ export default function pluginOpenAPIDocs(
   let docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
 
   async function generateApiDocs(options: APIOptions, pluginId: any) {
-    let { specPath, outputDir, template, sidebarOptions } = options;
+    let { specPath, outputDir, template, downloadUrl, sidebarOptions } =
+      options;
 
     // Override docPath if pluginId provided
     if (pluginId) {
@@ -217,6 +218,11 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
       `;
 
       loadedApi.map(async (item) => {
+        if (item.type === "info") {
+          if (downloadUrl && isURL(downloadUrl)) {
+            item.downloadUrl = downloadUrl;
+          }
+        }
         const markdown =
           item.type === "api"
             ? createApiPageMD(item)

package/src/markdown/createDownload.ts

@@ -0,0 +1,15 @@
+/* ============================================================================
+ * 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 { create, guard } from "./utils";
+
+export function createDownload(url: string | undefined) {
+  return guard(url, (url) => [
+    create("Export", { url: url, proxy: undefined }),
+    `\n\n`,
+  ]);
+}

package/src/markdown/createResponseSchema.ts

@@ -746,7 +746,8 @@ export function createResponseSchema({ title, body, ...rest }: Props) {
           value: `${mimeType}`,
           children: [
             create("SchemaTabs", {
-              groupId: "schema-tabs",
+              // TODO: determine if we should persist this
+              // groupId: "schema-tabs",
               children: [
                 firstBody &&
                   create("TabItem", {

package/src/markdown/index.ts

@@ -16,6 +16,7 @@ import { createAuthentication } from "./createAuthentication";
 import { createContactInfo } from "./createContactInfo";
 import { createDeprecationNotice } from "./createDeprecationNotice";
 import { createDescription } from "./createDescription";
+import { createDownload } from "./createDownload";
 import { createLicense } from "./createLicense";
 import { createLogo } from "./createLogo";
 import { createParamsDetails } from "./createParamsDetails";
@@ -83,13 +84,16 @@ export function createInfoPageMD({
     darkLogo,
   },
   securitySchemes,
+  downloadUrl,
 }: InfoPageMetadata) {
   return render([
     `import ApiLogo from "@theme/ApiLogo";\n`,
     `import Tabs from "@theme/Tabs";\n`,
-    `import TabItem from "@theme/TabItem";\n\n`,
+    `import TabItem from "@theme/TabItem";\n`,
+    `import Export from "@theme/ApiDemoPanel/Export";\n\n`,
 
     createVersionBadge(version),
+    createDownload(downloadUrl),
     `# ${title.replace(lessThan, "<").replace(greaterThan, ">")}\n\n`,
     createLogo(logo, darkLogo),
     createDescription(description),

package/src/markdown/utils.ts

@@ -43,6 +43,6 @@ export function render(children: Children): string {
 
 // Regex to selectively URL-encode '>' and '<' chars
 export const lessThan =
-  /<(?!(button|\s?\/button|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|a|\s?\/a|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|div|\s?\/div|center|\s?\/center))/giu;
+  /<(?!(=|button|\s?\/button|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|a|\s?\/a|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|div|\s?\/div|center|\s?\/center))/giu;
 export const greaterThan =
-  /(?<!(button|details|summary|hr|br|span|strong|small|table|td|tr|th|h1|h2|h3|h4|h5|h6|title|p|em|b|i|u|strike|a|tag|li|ol|ul|img|div|center|\/|\s|"|'))>/giu;
+  /(?<!(button|details|summary|hr|br|span|strong|small|table|td|tr|th|h1|h2|h3|h4|h5|h6|title|p|em|b|i|u|strike|a|tag|li|ol|ul|img|div|center|\/|\s|"|'))>?!=/giu;

package/src/options.ts

@@ -25,6 +25,7 @@ export const OptionsSchema = Joi.object({
         specPath: Joi.string().required(),
         outputDir: Joi.string().required(),
         template: Joi.string(),
+        downloadUrl: Joi.string(),
         sidebarOptions: sidebarOptions,
         version: Joi.string().when("versions", {
           is: Joi.exist(),

package/src/types.ts

@@ -32,6 +32,7 @@ export interface APIOptions {
   specPath: string;
   outputDir: string;
   template?: string;
+  downloadUrl?: string;
   sidebarOptions?: SidebarOptions;
   version?: string;
   label?: string;
@@ -72,6 +73,7 @@ export interface ApiMetadataBase {
   unversionedId: string; // TODO new unversioned id => try to rename to "id"
   infoId?: string;
   infoPath?: string;
+  downloadUrl?: string;
   title: string;
   description: string;
   source: string; // @site aliased source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md"