docusaurus-plugin-openapi-docs 1.4.7 → 1.5.0

package/README.md

@@ -121,6 +121,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.                                                                                |
+| `proxy`          | `string` | `null`  | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser.                                     |
 | `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.                            |

package/lib/index.js

@@ -87,8 +87,8 @@ function pluginOpenAPIDocs(context, options) {
             ? specPath
             : path_1.default.resolve(siteDir, specPath);
         try {
-            const openapiFiles = await (0, openapi_1.readOpenapiFiles)(contentPath, options);
-            const [loadedApi, tags] = await (0, openapi_1.processOpenapiFiles)(openapiFiles, sidebarOptions);
+            const openapiFiles = await (0, openapi_1.readOpenapiFiles)(contentPath);
+            const [loadedApi, tags] = await (0, openapi_1.processOpenapiFiles)(openapiFiles, options, sidebarOptions);
             if (!fs_1.default.existsSync(outputDir)) {
                 try {
                     fs_1.default.mkdirSync(outputDir, { recursive: true });
@@ -143,6 +143,10 @@ sidebar_class_name: "{{{api.method}}} api-method"
 {{#infoPath}}
 info_path: {{{infoPath}}}
 {{/infoPath}}
+custom_edit_url: null
+{{#frontMatter.proxy}}
+proxy: {{{frontMatter.proxy}}}
+{{/frontMatter.proxy}}
 ---
 
 {{{markdown}}}

package/lib/markdown/createRequestSchema.js

@@ -480,6 +480,7 @@ function createEdges({ name, schema, required, discriminator, }) {
             collapsible: false,
             name,
             required: Array.isArray(required) ? required.includes(name) : required,
+            deprecated: mergedSchemas.deprecated,
             schemaDescription: mergedSchemas.description,
             schemaName: schemaName,
             qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
@@ -507,6 +508,7 @@ function createEdges({ name, schema, required, discriminator, }) {
         collapsible: false,
         name,
         required: Array.isArray(required) ? required.includes(name) : required,
+        deprecated: schema.deprecated,
         schemaDescription: schema.description,
         schemaName: schemaName,
         qualifierMessage: (0, schema_1.getQualifierMessage)(schema),

package/lib/markdown/createResponseSchema.js

@@ -479,6 +479,7 @@ function createEdges({ name, schema, required, discriminator, }) {
             collapsible: false,
             name,
             required: false,
+            deprecated: mergedSchemas.deprecated,
             schemaDescription: mergedSchemas.description,
             schemaName: schemaName,
             qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
@@ -506,6 +507,7 @@ function createEdges({ name, schema, required, discriminator, }) {
         collapsible: false,
         name,
         required: false,
+        deprecated: schema.deprecated,
         schemaDescription: schema.description,
         schemaName: schemaName,
         qualifierMessage: (0, schema_1.getQualifierMessage)(schema),

package/lib/markdown/index.js

@@ -26,7 +26,7 @@ function createApiPageMD({ title, api: { deprecated, "x-deprecated-description":
         `import MimeTabs from "@theme/MimeTabs";\n`,
         `import ParamsItem from "@theme/ParamsItem";\n`,
         `import ResponseSamples from "@theme/ResponseSamples";\n`,
-        `import SchemaItem from "@theme/SchemaItem"\n`,
+        `import SchemaItem from "@theme/SchemaItem";\n`,
         `import SchemaTabs from "@theme/SchemaTabs";\n`,
         `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
         `import TabItem from "@theme/TabItem";\n\n`,

package/lib/openapi/createRequestExample.js

@@ -76,7 +76,7 @@ const sampleRequestFromSchema = (schema = {}) => {
             const { mergedSchemas } = (0, createRequestSchema_1.mergeAllOf)(allOf);
             if (mergedSchemas.properties) {
                 for (const [key, value] of Object.entries(mergedSchemas.properties)) {
-                    if (value.readOnly && value.readOnly === true) {
+                    if ((value.readOnly && value.readOnly === true) || value.deprecated) {
                         delete mergedSchemas.properties[key];
                     }
                 }
@@ -99,14 +99,16 @@ const sampleRequestFromSchema = (schema = {}) => {
             for (let [name, prop] of Object.entries(properties !== null && properties !== void 0 ? properties : {})) {
                 if (prop.properties) {
                     for (const [key, value] of Object.entries(prop.properties)) {
-                        if (value.readOnly && value.readOnly === true) {
+                        if ((value.readOnly && value.readOnly === true) ||
+                            value.deprecated) {
                             delete prop.properties[key];
                         }
                     }
                 }
                 if (prop.items && prop.items.properties) {
                     for (const [key, value] of Object.entries(prop.items.properties)) {
-                        if (value.readOnly && value.readOnly === true) {
+                        if ((value.readOnly && value.readOnly === true) ||
+                            value.deprecated) {
                             delete prop.items.properties[key];
                         }
                     }
@@ -137,7 +139,7 @@ const sampleRequestFromSchema = (schema = {}) => {
             }
             return normalizeArray(schema.enum)[0];
         }
-        if (schema.readOnly && schema.readOnly === true) {
+        if ((schema.readOnly && schema.readOnly === true) || schema.deprecated) {
             return undefined;
         }
         return primitive(schema);

package/lib/openapi/createResponseExample.js

@@ -68,7 +68,8 @@ const sampleResponseFromSchema = (schema = {}) => {
             const { mergedSchemas } = (0, createResponseSchema_1.mergeAllOf)(allOf);
             if (mergedSchemas.properties) {
                 for (const [key, value] of Object.entries(mergedSchemas.properties)) {
-                    if (value.writeOnly && value.writeOnly === true) {
+                    if ((value.writeOnly && value.writeOnly === true) ||
+                        value.deprecated) {
                         delete mergedSchemas.properties[key];
                     }
                 }
@@ -99,14 +100,16 @@ const sampleResponseFromSchema = (schema = {}) => {
             for (let [name, prop] of Object.entries(properties !== null && properties !== void 0 ? properties : {})) {
                 if (prop.properties) {
                     for (const [key, value] of Object.entries(prop.properties)) {
-                        if (value.writeOnly && value.writeOnly === true) {
+                        if ((value.writeOnly && value.writeOnly === true) ||
+                            value.deprecated) {
                             delete prop.properties[key];
                         }
                     }
                 }
                 if (prop.items && prop.items.properties) {
                     for (const [key, value] of Object.entries(prop.items.properties)) {
-                        if (value.writeOnly && value.writeOnly === true) {
+                        if ((value.writeOnly && value.writeOnly === true) ||
+                            value.deprecated) {
                             delete prop.items.properties[key];
                         }
                     }
@@ -137,7 +140,7 @@ const sampleResponseFromSchema = (schema = {}) => {
             }
             return normalizeArray(schema.enum)[0];
         }
-        if (schema.writeOnly && schema.writeOnly === true) {
+        if ((schema.writeOnly && schema.writeOnly === true) || schema.deprecated) {
             return undefined;
         }
         return primitive(schema);

package/lib/openapi/openapi.d.ts

@@ -5,8 +5,8 @@ interface OpenApiFiles {
     sourceDirName: string;
     data: OpenApiObject;
 }
-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(openapiData: OpenApiObject, sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[]]>;
+export declare function readOpenapiFiles(openapiPath: string): Promise<OpenApiFiles[]>;
+export declare function processOpenapiFiles(files: OpenApiFiles[], options: APIOptions, sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[][]]>;
+export declare function processOpenapiFile(openapiData: OpenApiObject, options: APIOptions, sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[]]>;
 export declare function getTagDisplayName(tagName: string, tags: TagObject[]): string;
 export {};

package/lib/openapi/openapi.js

@@ -60,11 +60,12 @@ async function createPostmanCollection(openapiData) {
     }
     return await jsonToCollection(data);
 }
-function createItems(openapiData, sidebarOptions) {
+function createItems(openapiData, options, sidebarOptions) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
     // TODO: Find a better way to handle this
     let items = [];
-    const infoId = (0, kebabCase_1.default)(openapiData.info.title);
+    const infoIdSpaces = openapiData.info.title.replace(" ", "-").toLowerCase();
+    const infoId = (0, kebabCase_1.default)(infoIdSpaces);
     if (openapiData.info.description) {
         // Only create an info page if we have a description.
         const infoDescription = (_a = openapiData.info) === null || _a === void 0 ? void 0 : _a.description;
@@ -171,6 +172,7 @@ function createItems(openapiData, sidebarOptions) {
                             .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
                             .replace(/\s+$/, "")
                         : "",
+                    ...((options === null || options === void 0 ? void 0 : options.proxy) && { proxy: options.proxy }),
                 },
                 api: {
                     ...defaults,
@@ -248,7 +250,7 @@ function bindCollectionToApiItems(items, postmanCollection) {
         }
     });
 }
-async function readOpenapiFiles(openapiPath, options) {
+async function readOpenapiFiles(openapiPath) {
     if (!(0, index_1.isURL)(openapiPath)) {
         const stat = await fs_extra_1.default.lstat(openapiPath);
         if (stat.isDirectory()) {
@@ -281,10 +283,10 @@ async function readOpenapiFiles(openapiPath, options) {
     ];
 }
 exports.readOpenapiFiles = readOpenapiFiles;
-async function processOpenapiFiles(files, sidebarOptions) {
+async function processOpenapiFiles(files, options, sidebarOptions) {
     const promises = files.map(async (file) => {
         if (file.data !== undefined) {
-            const processedFile = await processOpenapiFile(file.data, sidebarOptions);
+            const processedFile = await processOpenapiFile(file.data, options, sidebarOptions);
             const itemsObjectsArray = processedFile[0].map((item) => ({
                 ...item,
             }));
@@ -315,9 +317,9 @@ async function processOpenapiFiles(files, sidebarOptions) {
     return [items, tags];
 }
 exports.processOpenapiFiles = processOpenapiFiles;
-async function processOpenapiFile(openapiData, sidebarOptions) {
+async function processOpenapiFile(openapiData, options, sidebarOptions) {
     const postmanCollection = await createPostmanCollection(openapiData);
-    const items = createItems(openapiData, sidebarOptions);
+    const items = createItems(openapiData, options, sidebarOptions);
     bindCollectionToApiItems(items, postmanCollection);
     let tags = [];
     if (openapiData.tags !== undefined) {

package/lib/openapi/openapi.test.js

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

package/lib/options.js

@@ -21,6 +21,7 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
     config: utils_validation_1.Joi.object()
         .pattern(/^/, utils_validation_1.Joi.object({
         specPath: utils_validation_1.Joi.string().required(),
+        proxy: utils_validation_1.Joi.string(),
         outputDir: utils_validation_1.Joi.string().required(),
         template: utils_validation_1.Joi.string(),
         downloadUrl: utils_validation_1.Joi.string(),

package/lib/types.d.ts

@@ -20,6 +20,7 @@ export interface APIOptions {
     versions?: {
         [key: string]: APIVersionOptions;
     };
+    proxy?: string;
 }
 export interface SidebarOptions {
     groupPathsBy?: string;

package/package.json

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

package/src/index.ts

@@ -106,9 +106,10 @@ export default function pluginOpenAPIDocs(
       : path.resolve(siteDir, specPath);
 
     try {
-      const openapiFiles = await readOpenapiFiles(contentPath, options);
+      const openapiFiles = await readOpenapiFiles(contentPath);
       const [loadedApi, tags] = await processOpenapiFiles(
         openapiFiles,
+        options,
         sidebarOptions!
       );
       if (!fs.existsSync(outputDir)) {
@@ -182,6 +183,10 @@ sidebar_class_name: "{{{api.method}}} api-method"
 {{#infoPath}}
 info_path: {{{infoPath}}}
 {{/infoPath}}
+custom_edit_url: null
+{{#frontMatter.proxy}}
+proxy: {{{frontMatter.proxy}}}
+{{/frontMatter.proxy}}
 ---
 
 {{{markdown}}}

package/src/markdown/createRequestSchema.ts

@@ -597,6 +597,7 @@ function createEdges({
       collapsible: false,
       name,
       required: Array.isArray(required) ? required.includes(name) : required,
+      deprecated: mergedSchemas.deprecated,
       schemaDescription: mergedSchemas.description,
       schemaName: schemaName,
       qualifierMessage: getQualifierMessage(schema),
@@ -630,6 +631,7 @@ function createEdges({
     collapsible: false,
     name,
     required: Array.isArray(required) ? required.includes(name) : required,
+    deprecated: schema.deprecated,
     schemaDescription: schema.description,
     schemaName: schemaName,
     qualifierMessage: getQualifierMessage(schema),

package/src/markdown/createResponseSchema.ts

@@ -597,6 +597,7 @@ function createEdges({
       collapsible: false,
       name,
       required: false,
+      deprecated: mergedSchemas.deprecated,
       schemaDescription: mergedSchemas.description,
       schemaName: schemaName,
       qualifierMessage: getQualifierMessage(schema),
@@ -630,6 +631,7 @@ function createEdges({
     collapsible: false,
     name,
     required: false,
+    deprecated: schema.deprecated,
     schemaDescription: schema.description,
     schemaName: schemaName,
     qualifierMessage: getQualifierMessage(schema),

package/src/markdown/index.ts

@@ -53,7 +53,7 @@ export function createApiPageMD({
     `import MimeTabs from "@theme/MimeTabs";\n`,
     `import ParamsItem from "@theme/ParamsItem";\n`,
     `import ResponseSamples from "@theme/ResponseSamples";\n`,
-    `import SchemaItem from "@theme/SchemaItem"\n`,
+    `import SchemaItem from "@theme/SchemaItem";\n`,
     `import SchemaTabs from "@theme/SchemaTabs";\n`,
     `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,

package/src/openapi/createRequestExample.ts

@@ -98,7 +98,7 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
         mergeAllOf(allOf);
       if (mergedSchemas.properties) {
         for (const [key, value] of Object.entries(mergedSchemas.properties)) {
-          if (value.readOnly && value.readOnly === true) {
+          if ((value.readOnly && value.readOnly === true) || value.deprecated) {
             delete mergedSchemas.properties[key];
           }
         }
@@ -121,7 +121,10 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
       for (let [name, prop] of Object.entries(properties ?? {})) {
         if (prop.properties) {
           for (const [key, value] of Object.entries(prop.properties)) {
-            if (value.readOnly && value.readOnly === true) {
+            if (
+              (value.readOnly && value.readOnly === true) ||
+              value.deprecated
+            ) {
               delete prop.properties[key];
             }
           }
@@ -129,7 +132,10 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
 
         if (prop.items && prop.items.properties) {
           for (const [key, value] of Object.entries(prop.items.properties)) {
-            if (value.readOnly && value.readOnly === true) {
+            if (
+              (value.readOnly && value.readOnly === true) ||
+              value.deprecated
+            ) {
               delete prop.items.properties[key];
             }
           }
@@ -168,7 +174,7 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
       return normalizeArray(schema.enum)[0];
     }
 
-    if (schema.readOnly && schema.readOnly === true) {
+    if ((schema.readOnly && schema.readOnly === true) || schema.deprecated) {
       return undefined;
     }
 

package/src/openapi/createResponseExample.ts

@@ -88,7 +88,10 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
         mergeAllOf(allOf);
       if (mergedSchemas.properties) {
         for (const [key, value] of Object.entries(mergedSchemas.properties)) {
-          if (value.writeOnly && value.writeOnly === true) {
+          if (
+            (value.writeOnly && value.writeOnly === true) ||
+            value.deprecated
+          ) {
             delete mergedSchemas.properties[key];
           }
         }
@@ -121,7 +124,10 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
       for (let [name, prop] of Object.entries(properties ?? {})) {
         if (prop.properties) {
           for (const [key, value] of Object.entries(prop.properties)) {
-            if (value.writeOnly && value.writeOnly === true) {
+            if (
+              (value.writeOnly && value.writeOnly === true) ||
+              value.deprecated
+            ) {
               delete prop.properties[key];
             }
           }
@@ -129,7 +135,10 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
 
         if (prop.items && prop.items.properties) {
           for (const [key, value] of Object.entries(prop.items.properties)) {
-            if (value.writeOnly && value.writeOnly === true) {
+            if (
+              (value.writeOnly && value.writeOnly === true) ||
+              value.deprecated
+            ) {
               delete prop.items.properties[key];
             }
           }
@@ -168,7 +177,7 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
       return normalizeArray(schema.enum)[0];
     }
 
-    if (schema.writeOnly && schema.writeOnly === true) {
+    if ((schema.writeOnly && schema.writeOnly === true) || schema.deprecated) {
       return undefined;
     }
 

package/src/openapi/openapi.test.ts

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

package/src/openapi/openapi.ts

@@ -80,11 +80,13 @@ type PartialPage<T> = Omit<T, "permalink" | "source" | "sourceDirName">;
 
 function createItems(
   openapiData: OpenApiObject,
+  options: APIOptions,
   sidebarOptions: SidebarOptions
 ): ApiMetadata[] {
   // TODO: Find a better way to handle this
   let items: PartialPage<ApiMetadata>[] = [];
-  const infoId = kebabCase(openapiData.info.title);
+  const infoIdSpaces = openapiData.info.title.replace(" ", "-").toLowerCase();
+  const infoId = kebabCase(infoIdSpaces);
 
   if (openapiData.info.description) {
     // Only create an info page if we have a description.
@@ -218,6 +220,7 @@ function createItems(
                 .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
                 .replace(/\s+$/, "")
             : "",
+          ...(options?.proxy && { proxy: options.proxy }),
         },
         api: {
           ...defaults,
@@ -318,8 +321,7 @@ interface OpenApiFiles {
 }
 
 export async function readOpenapiFiles(
-  openapiPath: string,
-  options: APIOptions
+  openapiPath: string
 ): Promise<OpenApiFiles[]> {
   if (!isURL(openapiPath)) {
     const stat = await fs.lstat(openapiPath);
@@ -361,11 +363,16 @@ export async function readOpenapiFiles(
 
 export async function processOpenapiFiles(
   files: OpenApiFiles[],
+  options: APIOptions,
   sidebarOptions: SidebarOptions
 ): Promise<[ApiMetadata[], TagObject[][]]> {
   const promises = files.map(async (file) => {
     if (file.data !== undefined) {
-      const processedFile = await processOpenapiFile(file.data, sidebarOptions);
+      const processedFile = await processOpenapiFile(
+        file.data,
+        options,
+        sidebarOptions
+      );
       const itemsObjectsArray = processedFile[0].map((item) => ({
         ...item,
       }));
@@ -402,10 +409,11 @@ export async function processOpenapiFiles(
 
 export async function processOpenapiFile(
   openapiData: OpenApiObject,
+  options: APIOptions,
   sidebarOptions: SidebarOptions
 ): Promise<[ApiMetadata[], TagObject[]]> {
   const postmanCollection = await createPostmanCollection(openapiData);
-  const items = createItems(openapiData, sidebarOptions);
+  const items = createItems(openapiData, options, sidebarOptions);
 
   bindCollectionToApiItems(items, postmanCollection);
 

package/src/options.ts

@@ -23,6 +23,7 @@ export const OptionsSchema = Joi.object({
       /^/,
       Joi.object({
         specPath: Joi.string().required(),
+        proxy: Joi.string(),
         outputDir: Joi.string().required(),
         template: Joi.string(),
         downloadUrl: Joi.string(),

package/src/types.ts

@@ -40,6 +40,7 @@ export interface APIOptions {
   versions?: {
     [key: string]: APIVersionOptions;
   };
+  proxy?: string;
 }
 
 export interface SidebarOptions {