docusaurus-plugin-openapi-docs 1.2.2 → 1.3.1

package/lib/markdown/createDescription.js

@@ -7,10 +7,13 @@
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createDescription = void 0;
+const utils_1 = require("./utils");
 function createDescription(description) {
     if (!description) {
         return "";
     }
-    return `\n\n${description}\n\n`;
+    return `\n\n${description
+        .replace(utils_1.lessThan, "<")
+        .replace(utils_1.greaterThan, ">")}\n\n`;
 }
 exports.createDescription = createDescription;

package/lib/markdown/createRequestSchema.js

@@ -566,7 +566,7 @@ function createRequestSchema({ title, body, ...rest }) {
     const mimeTypes = Object.keys(body.content);
     if (mimeTypes && mimeTypes.length > 1) {
         return (0, utils_1.create)("MimeTabs", {
-            groupId: "mime-type",
+            schemaType: "request",
             children: mimeTypes.map((mimeType) => {
                 const firstBody = body.content[mimeType].schema;
                 if (firstBody === undefined) {

package/lib/markdown/createResponseSchema.js

@@ -566,7 +566,7 @@ function createResponseSchema({ title, body, ...rest }) {
     const mimeTypes = Object.keys(body.content);
     if (mimeTypes && mimeTypes.length) {
         return (0, utils_1.create)("MimeTabs", {
-            groupId: "mime-type",
+            schemaType: "response",
             children: mimeTypes.map((mimeType) => {
                 const responseExamples = body.content[mimeType].examples;
                 const responseExample = body.content[mimeType].example;

package/lib/markdown/index.js

@@ -7,7 +7,6 @@
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTagPageMD = exports.createInfoPageMD = exports.createApiPageMD = void 0;
-const lodash_1 = require("lodash");
 const createAuthentication_1 = require("./createAuthentication");
 const createContactInfo_1 = require("./createContactInfo");
 const createDeprecationNotice_1 = require("./createDeprecationNotice");
@@ -30,9 +29,9 @@ function createApiPageMD({ title, api: { deprecated, "x-deprecated-description":
         `import SchemaTabs from "@theme/SchemaTabs";\n`,
         `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
         `import TabItem from "@theme/TabItem";\n\n`,
-        `## ${(0, lodash_1.escape)(title)}\n\n`,
+        `## ${title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")}\n\n`,
         (0, createDeprecationNotice_1.createDeprecationNotice)({ deprecated, description: deprecatedDescription }),
-        (0, createDescription_1.createDescription)((0, lodash_1.escape)(description)),
+        (0, createDescription_1.createDescription)(description),
         (0, createParamsDetails_1.createParamsDetails)({ parameters, type: "path" }),
         (0, createParamsDetails_1.createParamsDetails)({ parameters, type: "query" }),
         (0, createParamsDetails_1.createParamsDetails)({ parameters, type: "header" }),
@@ -51,7 +50,7 @@ function createInfoPageMD({ info: { title, version, description, contact, licens
         `import Tabs from "@theme/Tabs";\n`,
         `import TabItem from "@theme/TabItem";\n\n`,
         (0, createVersionBadge_1.createVersionBadge)(version),
-        `# ${(0, lodash_1.escape)(title)}\n\n`,
+        `# ${title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")}\n\n`,
         (0, createLogo_1.createLogo)(logo, darkLogo),
         (0, createDescription_1.createDescription)(description),
         (0, createAuthentication_1.createAuthentication)(securitySchemes),

package/lib/markdown/utils.d.ts

@@ -5,3 +5,5 @@ export declare type Props = Record<string, any> & {
 export declare function create(tag: string, props: Props): string;
 export declare function guard<T>(value: T | undefined, cb: (value: T) => Children): string;
 export declare function render(children: Children): string;
+export declare const lessThan: RegExp;
+export declare const greaterThan: RegExp;

package/lib/markdown/utils.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.render = exports.guard = exports.create = void 0;
+exports.greaterThan = exports.lessThan = exports.render = exports.guard = exports.create = void 0;
 function create(tag, props) {
     const { children, ...rest } = props;
     let propString = "";
@@ -34,3 +34,6 @@ function render(children) {
     return children !== null && children !== void 0 ? 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;

package/lib/openapi/createResponseExample.js

@@ -60,12 +60,10 @@ function sampleResponseFromProp(name, prop, obj) {
 }
 const sampleResponseFromSchema = (schema = {}) => {
     try {
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
         let { type, example, allOf, oneOf, anyOf, properties, items } = schema;
-        // TODO: determine if we should always ignore the example when creating from schema
-        // if (example !== undefined) {
-        //   return example;
-        // }
+        if (example !== undefined) {
+            return example;
+        }
         if (allOf) {
             const { mergedSchemas } = (0, createResponseSchema_1.mergeAllOf)(allOf);
             if (mergedSchemas.properties) {

package/lib/openapi/openapi.js

@@ -18,6 +18,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const cloneDeep_1 = __importDefault(require("lodash/cloneDeep"));
 const kebabCase_1 = __importDefault(require("lodash/kebabCase"));
+const unionBy_1 = __importDefault(require("lodash/unionBy"));
 const index_1 = require("../index");
 const createRequestExample_1 = require("./createRequestExample");
 const loadAndResolveSpec_1 = require("./utils/loadAndResolveSpec");
@@ -151,6 +152,16 @@ function createItems(openapiData, sidebarOptions) {
             }
             // TODO: Don't include summary temporarilly
             const { summary, ...defaults } = operationObject;
+            // Merge common parameters with operation parameters
+            // Operation params take precendence over common params
+            if (parameters !== undefined) {
+                if (operationObject.parameters !== undefined) {
+                    defaults.parameters = (0, unionBy_1.default)(operationObject.parameters, parameters, "name");
+                }
+                else {
+                    defaults.parameters = parameters;
+                }
+            }
             const apiPage = {
                 type: "api",
                 id: baseId,
@@ -202,7 +213,6 @@ async function readOpenapiFiles(openapiPath, options) {
     if (!(0, index_1.isURL)(openapiPath)) {
         const stat = await fs_extra_1.default.lstat(openapiPath);
         if (stat.isDirectory()) {
-            console.warn(chalk_1.default.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 (0, utils_1.Globby)(["**/*.{json,yaml,yml}"], {
                 cwd: openapiPath,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -68,5 +68,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "cfeb5216f143133a1c35587fef21f75a44b75854"
+  "gitHead": "5f41e8dc4981409902ae96a7d127a2ae7eb9a47d"
 }

package/src/markdown/createDescription.ts

@@ -5,9 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import { greaterThan, lessThan } from "./utils";
+
 export function createDescription(description: string | undefined) {
   if (!description) {
     return "";
   }
-  return `\n\n${description}\n\n`;
+  return `\n\n${description
+    .replace(lessThan, "<")
+    .replace(greaterThan, ">")}\n\n`;
 }

package/src/markdown/createRequestSchema.ts

@@ -721,7 +721,7 @@ export function createRequestSchema({ title, body, ...rest }: Props) {
 
   if (mimeTypes && mimeTypes.length > 1) {
     return create("MimeTabs", {
-      groupId: "mime-type",
+      schemaType: "request",
       children: mimeTypes.map((mimeType) => {
         const firstBody = body.content![mimeType].schema;
         if (firstBody === undefined) {

package/src/markdown/createResponseSchema.ts

@@ -721,7 +721,7 @@ export function createResponseSchema({ title, body, ...rest }: Props) {
 
   if (mimeTypes && mimeTypes.length) {
     return create("MimeTabs", {
-      groupId: "mime-type",
+      schemaType: "response",
       children: mimeTypes.map((mimeType: any) => {
         const responseExamples = body.content![mimeType].examples;
         const responseExample = body.content![mimeType].example;

package/src/markdown/index.ts

@@ -5,8 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { escape } from "lodash";
-
 import {
   ContactObject,
   LicenseObject,
@@ -25,7 +23,7 @@ import { createRequestBodyDetails } from "./createRequestBodyDetails";
 import { createStatusCodes } from "./createStatusCodes";
 import { createTermsOfService } from "./createTermsOfService";
 import { createVersionBadge } from "./createVersionBadge";
-import { render } from "./utils";
+import { greaterThan, lessThan, render } from "./utils";
 
 interface Props {
   title: string;
@@ -58,9 +56,9 @@ export function createApiPageMD({
     `import SchemaTabs from "@theme/SchemaTabs";\n`,
     `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,
-    `## ${escape(title)}\n\n`,
+    `## ${title.replace(lessThan, "<").replace(greaterThan, ">")}\n\n`,
     createDeprecationNotice({ deprecated, description: deprecatedDescription }),
-    createDescription(escape(description)),
+    createDescription(description),
     createParamsDetails({ parameters, type: "path" }),
     createParamsDetails({ parameters, type: "query" }),
     createParamsDetails({ parameters, type: "header" }),
@@ -92,7 +90,7 @@ export function createInfoPageMD({
     `import TabItem from "@theme/TabItem";\n\n`,
 
     createVersionBadge(version),
-    `# ${escape(title)}\n\n`,
+    `# ${title.replace(lessThan, "<").replace(greaterThan, ">")}\n\n`,
     createLogo(logo, darkLogo),
     createDescription(description),
     createAuthentication(securitySchemes as unknown as SecuritySchemeObject),

package/src/markdown/utils.ts

@@ -40,3 +40,9 @@ export function render(children: Children): string {
   }
   return children ?? "";
 }
+
+// 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;
+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;

package/src/openapi/createResponseExample.ts

@@ -77,13 +77,11 @@ function sampleResponseFromProp(name: string, prop: any, obj: any): any {
 
 export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
   try {
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     let { type, example, allOf, oneOf, anyOf, properties, items } = schema;
 
-    // TODO: determine if we should always ignore the example when creating from schema
-    // if (example !== undefined) {
-    //   return example;
-    // }
+    if (example !== undefined) {
+      return example;
+    }
 
     if (allOf) {
       const { mergedSchemas }: { mergedSchemas: SchemaObject } =

package/src/openapi/openapi.ts

@@ -15,6 +15,7 @@ import chalk from "chalk";
 import fs from "fs-extra";
 import cloneDeep from "lodash/cloneDeep";
 import kebabCase from "lodash/kebabCase";
+import unionBy from "lodash/unionBy";
 
 import { isURL } from "../index";
 import {
@@ -193,6 +194,20 @@ function createItems(
       // TODO: Don't include summary temporarilly
       const { summary, ...defaults } = operationObject;
 
+      // Merge common parameters with operation parameters
+      // Operation params take precendence over common params
+      if (parameters !== undefined) {
+        if (operationObject.parameters !== undefined) {
+          defaults.parameters = unionBy(
+            operationObject.parameters,
+            parameters,
+            "name"
+          );
+        } else {
+          defaults.parameters = parameters;
+        }
+      }
+
       const apiPage: PartialPage<ApiPageMetadata> = {
         type: "api",
         id: baseId,
@@ -265,12 +280,6 @@ export async function readOpenapiFiles(
   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,