docusaurus-plugin-openapi-docs 4.3.7 → 4.5.0

package/src/openapi/createSchemaExample.ts

@@ -0,0 +1,292 @@
+/* ============================================================================
+ * 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 chalk from "chalk";
+import merge from "lodash/merge";
+
+import { SchemaObject } from "./types";
+import { mergeAllOf } from "../markdown/createSchema";
+
+interface OASTypeToTypeMap {
+  string: string;
+  number: number;
+  integer: number;
+  boolean: boolean;
+  object: any;
+  array: any[];
+  null: string | null;
+}
+
+type Primitives = {
+  [OASType in keyof OASTypeToTypeMap]: {
+    [format: string]: (schema: SchemaObject) => OASTypeToTypeMap[OASType];
+  };
+};
+
+const primitives: Primitives = {
+  string: {
+    default: () => "string",
+    email: () => "user@example.com",
+    date: () => "2024-07-29",
+    "date-time": () => "2024-07-29T15:51:28.071Z",
+    uuid: () => "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    hostname: () => "example.com",
+    ipv4: () => "198.51.100.42",
+    ipv6: () => "2001:0db8:5b96:0000:0000:426f:8e17:642a",
+  },
+  number: {
+    default: () => 0,
+    float: () => 0.0,
+  },
+  integer: {
+    default: () => 0,
+  },
+  boolean: {
+    default: (schema) =>
+      typeof schema.default === "boolean" ? schema.default : true,
+  },
+  object: {},
+  array: {},
+  null: {
+    default: () => "null",
+  },
+};
+
+type ExampleType = "request" | "response";
+
+interface ExampleContext {
+  type: ExampleType;
+}
+
+function shouldExcludeProperty(
+  prop: SchemaObject,
+  context: ExampleContext
+): boolean {
+  if (prop.deprecated) {
+    return true;
+  }
+
+  if (context.type === "request") {
+    return prop.readOnly === true;
+  } else {
+    return prop.writeOnly === true;
+  }
+}
+
+function sampleFromProp(
+  name: string,
+  prop: any,
+  obj: any,
+  context: ExampleContext
+): any {
+  // Handle resolved circular props
+  if (typeof prop === "object" && Object.keys(prop).length === 0) {
+    obj[name] = prop;
+    return obj;
+  }
+
+  // TODO: handle discriminators
+
+  if (prop.oneOf) {
+    obj[name] = sampleFromSchema(prop.oneOf[0], context);
+  } else if (prop.anyOf) {
+    obj[name] = sampleFromSchema(prop.anyOf[0], context);
+  } else if (prop.allOf) {
+    const mergedSchemas = mergeAllOf(prop) as SchemaObject;
+    sampleFromProp(name, mergedSchemas, obj, context);
+  } else {
+    obj[name] = sampleFromSchema(prop, context);
+  }
+  return obj;
+}
+
+export const sampleFromSchema = (
+  schema: SchemaObject = {},
+  context: ExampleContext
+): any => {
+  try {
+    // deep copy schema before processing
+    let schemaCopy = JSON.parse(JSON.stringify(schema));
+    let { type, example, allOf, properties, items, oneOf, anyOf } = schemaCopy;
+
+    if (example !== undefined) {
+      return example;
+    }
+
+    if (oneOf) {
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, oneOf[0]);
+        delete combinedSchemas.oneOf;
+        return sampleFromSchema(combinedSchemas, context);
+      }
+      // Just go with first schema
+      return sampleFromSchema(oneOf[0], context);
+    }
+
+    if (anyOf) {
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, anyOf[0]);
+        delete combinedSchemas.anyOf;
+        return sampleFromSchema(combinedSchemas, context);
+      }
+      // Just go with first schema
+      return sampleFromSchema(anyOf[0], context);
+    }
+
+    if (allOf) {
+      const mergedSchemas = mergeAllOf(schemaCopy) as SchemaObject;
+      if (mergedSchemas.properties) {
+        for (const [key, value] of Object.entries(mergedSchemas.properties)) {
+          if (shouldExcludeProperty(value, context)) {
+            delete mergedSchemas.properties[key];
+          }
+        }
+      }
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, mergedSchemas);
+        delete combinedSchemas.allOf;
+        return sampleFromSchema(combinedSchemas, context);
+      }
+      return sampleFromSchema(mergedSchemas, context);
+    }
+
+    if (!type) {
+      if (properties) {
+        type = "object";
+      } else if (items) {
+        type = "array";
+      } else {
+        return;
+      }
+    }
+
+    if (type === "object") {
+      let obj: any = {};
+      for (let [name, prop] of Object.entries(properties ?? {}) as any) {
+        if (prop.properties) {
+          for (const [key, value] of Object.entries(prop.properties) as any) {
+            if (shouldExcludeProperty(value, context)) {
+              delete prop.properties[key];
+            }
+          }
+        }
+
+        if (prop.items && prop.items.properties) {
+          for (const [key, value] of Object.entries(
+            prop.items.properties
+          ) as any) {
+            if (shouldExcludeProperty(value, context)) {
+              delete prop.items.properties[key];
+            }
+          }
+        }
+
+        if (shouldExcludeProperty(prop, context)) {
+          continue;
+        }
+
+        // Resolve schema from prop recursively
+        obj = sampleFromProp(name, prop, obj, context);
+      }
+      return obj;
+    }
+
+    if (type === "array") {
+      if (Array.isArray(items?.anyOf)) {
+        return processArrayItems(items, "anyOf", context);
+      }
+
+      if (Array.isArray(items?.oneOf)) {
+        return processArrayItems(items, "oneOf", context);
+      }
+
+      return normalizeArray(sampleFromSchema(items, context));
+    }
+
+    if (schemaCopy.enum) {
+      if (schemaCopy.default) {
+        return schemaCopy.default;
+      }
+      return normalizeArray(schemaCopy.enum)[0];
+    }
+
+    if (shouldExcludeProperty(schemaCopy, context)) {
+      return undefined;
+    }
+
+    return primitive(schemaCopy);
+  } catch (err) {
+    console.error(
+      chalk.yellow("WARNING: failed to create example from schema object:", err)
+    );
+    return;
+  }
+};
+
+function primitive(schema: SchemaObject = {}) {
+  let { type, format } = schema;
+
+  if (type === undefined) {
+    return;
+  }
+
+  // If type is an array, use the first type
+  if (Array.isArray(type)) {
+    type = type[0];
+    if (type === undefined) {
+      return;
+    }
+  }
+
+  // Use schema default if available, otherwise use type default
+  if (schema.default !== undefined) {
+    return schema.default;
+  }
+
+  const typeConfig = primitives[type];
+  if (typeConfig) {
+    if (format !== undefined && typeConfig[format] !== undefined) {
+      return typeConfig[format](schema);
+    }
+    if (typeConfig.default !== undefined) {
+      return typeConfig.default(schema);
+    }
+  }
+
+  return "Unknown Type: " + schema.type;
+}
+
+function normalizeArray(arr: any) {
+  if (Array.isArray(arr)) {
+    return arr;
+  }
+  return [arr];
+}
+
+function processArrayItems(
+  items: SchemaObject,
+  schemaType: "anyOf" | "oneOf",
+  context: ExampleContext
+): any[] {
+  const itemsArray = items[schemaType] as SchemaObject[];
+  return itemsArray.map((item: SchemaObject) => {
+    // If items has properties, merge them with each item
+    if (items.properties) {
+      const combinedSchema = {
+        ...item,
+        properties: {
+          ...items.properties, // Common properties from parent
+          ...item.properties, // Specific properties from this anyOf/oneOf item
+        },
+      };
+      // Remove anyOf/oneOf to prevent infinite recursion when calling sampleFromSchema
+      delete combinedSchema[schemaType];
+      return sampleFromSchema(combinedSchema, context);
+    }
+    return sampleFromSchema(item, context);
+  });
+}

package/src/openapi/openapi.ts

@@ -15,8 +15,8 @@ import kebabCase from "lodash/kebabCase";
 import unionBy from "lodash/unionBy";
 import uniq from "lodash/uniq";
 import Converter from "openapi-to-postmanv2";
-import Collection from "postman-collection";
-import sdk from "postman-collection";
+import { Collection } from "postman-collection";
+import * as sdk from "postman-collection";
 
 import { sampleRequestFromSchema } from "./createRequestExample";
 import { OpenApiObject, TagGroupObject, TagObject } from "./types";
@@ -263,6 +263,7 @@ function createItems(
           jsonRequestBodyExample,
           info: openapiData.info,
         },
+        position: operationObject["x-position"] as number | undefined,
       };
 
       items.push(apiPage);
@@ -509,6 +510,22 @@ function createItems(
       });
   }
 
+  items.sort((a, b) => {
+    // Items with position come first, sorted by position
+    if (a.position !== undefined && b.position !== undefined) {
+      return a.position - b.position;
+    }
+    // Items with position come before items without position
+    if (a.position !== undefined) {
+      return -1;
+    }
+    if (b.position !== undefined) {
+      return 1;
+    }
+    // If neither has position, maintain original order
+    return 0;
+  });
+
   return items as ApiMetadata[];
 }
 

package/src/openapi/types.ts

@@ -5,11 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import type { JSONSchema4, JSONSchema6, JSONSchema7 } from "json-schema";
-
-interface Map<T> {
-  [key: string]: T;
-}
+import type {
+  JSONSchema4,
+  JSONSchema6,
+  JSONSchema7,
+  JSONSchema7TypeName,
+} from "json-schema";
 
 export interface OpenApiObject {
   openapi: string;
@@ -69,7 +70,7 @@ export interface LicenseObject {
 export interface ServerObject {
   url: string;
   description?: string;
-  variables?: Map<ServerVariable>;
+  variables?: Record<string, ServerVariable>;
 }
 
 export interface ServerVariable {
@@ -79,32 +80,32 @@ export interface ServerVariable {
 }
 
 export interface ComponentsObject {
-  schemas?: Map<SchemaObject>;
-  responses?: Map<ResponseObject>;
-  parameters?: Map<ParameterObject>;
-  examples?: Map<ExampleObject>;
-  requestBodies?: Map<RequestBodyObject>;
-  headers?: Map<HeaderObject>;
-  securitySchemes?: Map<SecuritySchemeObject>;
-  links?: Map<LinkObject>;
-  callbacks?: Map<CallbackObject>;
+  schemas?: Record<string, SchemaObject>;
+  responses?: Record<string, ResponseObject>;
+  parameters?: Record<string, ParameterObject>;
+  examples?: Record<string, ExampleObject>;
+  requestBodies?: Record<string, RequestBodyObject>;
+  headers?: Record<string, HeaderObject>;
+  securitySchemes?: Record<string, SecuritySchemeObject>;
+  links?: Record<string, LinkObject>;
+  callbacks?: Record<string, CallbackObject>;
 }
 
 export interface ComponentsObjectWithRef {
-  schemas?: Map<SchemaObjectWithRef | ReferenceObject>;
-  responses?: Map<ResponseObjectWithRef | ReferenceObject>;
-  parameters?: Map<ParameterObjectWithRef | ReferenceObject>;
-  examples?: Map<ExampleObject | ReferenceObject>;
-  requestBodies?: Map<RequestBodyObjectWithRef | ReferenceObject>;
-  headers?: Map<HeaderObjectWithRef | ReferenceObject>;
-  securitySchemes?: Map<SecuritySchemeObject | ReferenceObject>;
-  links?: Map<LinkObject | ReferenceObject>;
-  callbacks?: Map<CallbackObjectWithRef | ReferenceObject>;
+  schemas?: Record<string, SchemaObjectWithRef | ReferenceObject>;
+  responses?: Record<string, ResponseObjectWithRef | ReferenceObject>;
+  parameters?: Record<string, ParameterObjectWithRef | ReferenceObject>;
+  examples?: Record<string, ExampleObject | ReferenceObject>;
+  requestBodies?: Record<string, RequestBodyObjectWithRef | ReferenceObject>;
+  headers?: Record<string, HeaderObjectWithRef | ReferenceObject>;
+  securitySchemes?: Record<string, SecuritySchemeObject | ReferenceObject>;
+  links?: Record<string, LinkObject | ReferenceObject>;
+  callbacks?: Record<string, CallbackObjectWithRef | ReferenceObject>;
 }
 
-export type PathsObject = Map<PathItemObject>;
+export type PathsObject = Record<string, PathItemObject>;
 
-export type PathsObjectWithRef = Map<PathItemObjectWithRef>;
+export type PathsObjectWithRef = Record<string, PathItemObjectWithRef>;
 
 export interface PathItemObject {
   $ref?: string;
@@ -147,12 +148,12 @@ export interface OperationObject {
   parameters?: ParameterObject[];
   requestBody?: RequestBodyObject;
   responses: ResponsesObject;
-  callbacks?: Map<CallbackObject>;
+  callbacks?: Record<string, CallbackObject>;
   deprecated?: boolean;
   security?: SecurityRequirementObject[];
   servers?: ServerObject[];
-
   // extensions
+  "x-position"?: number;
   "x-deprecated-description"?: string;
 }
 
@@ -165,7 +166,7 @@ export interface OperationObjectWithRef {
   parameters?: (ParameterObjectWithRef | ReferenceObject)[];
   requestBody?: RequestBodyObjectWithRef | ReferenceObject;
   responses: ResponsesObjectWithRef;
-  callbacks?: Map<CallbackObjectWithRef | ReferenceObject>;
+  callbacks?: Record<string, CallbackObjectWithRef | ReferenceObject>;
   deprecated?: boolean;
   security?: SecurityRequirementObject[];
   servers?: ServerObject[];
@@ -192,9 +193,9 @@ export interface ParameterObject {
   allowReserved?: boolean;
   schema?: SchemaObject;
   example?: any;
-  examples?: Map<ExampleObject>;
+  examples?: Record<string, ExampleObject>;
   //
-  content?: Map<MediaTypeObject>;
+  content?: Record<string, MediaTypeObject>;
   param?: Object;
   // ignoring stylings: matrix, label, form, simple, spaceDelimited,
   // pipeDelimited and deepObject
@@ -214,43 +215,43 @@ export interface ParameterObjectWithRef {
   allowReserved?: boolean;
   schema?: SchemaObjectWithRef | ReferenceObject;
   example?: any;
-  examples?: Map<ExampleObject | ReferenceObject>;
+  examples?: Record<string, ExampleObject | ReferenceObject>;
   //
-  content?: Map<MediaTypeObjectWithRef>;
+  content?: Record<string, MediaTypeObjectWithRef>;
   // ignoring stylings: matrix, label, form, simple, spaceDelimited,
   // pipeDelimited and deepObject
 }
 
 export interface RequestBodyObject {
   description?: string;
-  content: Map<MediaTypeObject>;
+  content: Record<string, MediaTypeObject>;
   required?: boolean;
 }
 
 export interface RequestBodyObjectWithRef {
   description?: string;
-  content: Map<MediaTypeObjectWithRef>;
+  content: Record<string, MediaTypeObjectWithRef>;
   required?: boolean;
 }
 
 export interface MediaTypeObject {
   schema?: SchemaObject;
   example?: any;
-  examples?: Map<ExampleObject>;
-  encoding?: Map<EncodingObject>;
+  examples?: Record<string, ExampleObject>;
+  encoding?: Record<string, EncodingObject>;
   type?: any;
 }
 
 export interface MediaTypeObjectWithRef {
   schema?: SchemaObjectWithRef | ReferenceObject;
   example?: any;
-  examples?: Map<ExampleObject | ReferenceObject>;
-  encoding?: Map<EncodingObjectWithRef>;
+  examples?: Record<string, ExampleObject | ReferenceObject>;
+  encoding?: Record<string, EncodingObjectWithRef>;
 }
 
 export interface EncodingObject {
   contentType?: string;
-  headers?: Map<HeaderObject>;
+  headers?: Record<string, HeaderObject>;
   style?: string;
   explode?: boolean;
   allowReserved?: boolean;
@@ -258,35 +259,36 @@ export interface EncodingObject {
 
 export interface EncodingObjectWithRef {
   contentType?: string;
-  headers?: Map<HeaderObjectWithRef | ReferenceObject>;
+  headers?: Record<string, HeaderObjectWithRef | ReferenceObject>;
   style?: string;
   explode?: boolean;
   allowReserved?: boolean;
 }
 
-export type ResponsesObject = Map<ResponseObject>;
+export type ResponsesObject = Record<string, ResponseObject>;
 
-export type ResponsesObjectWithRef = Map<
+export type ResponsesObjectWithRef = Record<
+  string,
   ResponseObjectWithRef | ReferenceObject
 >;
 
 export interface ResponseObject {
   description: string;
-  headers?: Map<HeaderObject>;
-  content?: Map<MediaTypeObject>;
-  links?: Map<LinkObject>;
+  headers?: Record<string, HeaderObject>;
+  content?: Record<string, MediaTypeObject>;
+  links?: Record<string, LinkObject>;
 }
 
 export interface ResponseObjectWithRef {
   description: string;
-  headers?: Map<HeaderObjectWithRef | ReferenceObject>;
-  content?: Map<MediaTypeObjectWithRef>;
-  links?: Map<LinkObject | ReferenceObject>;
+  headers?: Record<string, HeaderObjectWithRef | ReferenceObject>;
+  content?: Record<string, MediaTypeObjectWithRef>;
+  links?: Record<string, LinkObject | ReferenceObject>;
 }
 
-export type CallbackObject = Map<PathItemObject>;
+export type CallbackObject = Record<string, PathItemObject>;
 
-export type CallbackObjectWithRef = Map<PathItemObjectWithRef>;
+export type CallbackObjectWithRef = Record<string, PathItemObjectWithRef>;
 
 export interface ExampleObject {
   summary?: string;
@@ -298,7 +300,7 @@ export interface ExampleObject {
 export interface LinkObject {
   operationRef?: string;
   operationId?: string;
-  parameters?: Map<any>;
+  parameters?: Record<string, any>;
   requestBody?: any;
   description?: string;
   server?: ServerObject;
@@ -325,6 +327,7 @@ export interface ReferenceObject {
 }
 
 export type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
+export type SchemaType = JSONSchema7TypeName;
 export type SchemaObject = Omit<
   JSONSchema,
   | "type"
@@ -337,13 +340,13 @@ export type SchemaObject = Omit<
   | "additionalProperties"
 > & {
   // OpenAPI specific overrides
-  type?: "string" | "number" | "integer" | "boolean" | "object" | "array";
+  type?: SchemaType;
   allOf?: SchemaObject[];
   oneOf?: SchemaObject[];
   anyOf?: SchemaObject[];
   not?: SchemaObject;
   items?: SchemaObject;
-  properties?: Map<SchemaObject>;
+  properties?: Record<string, SchemaObject>;
   additionalProperties?: boolean | SchemaObject;
 
   // OpenAPI additions
@@ -371,13 +374,13 @@ export type SchemaObjectWithRef = Omit<
   | "additionalProperties"
 > & {
   // OpenAPI specific overrides
-  type?: "string" | "number" | "integer" | "boolean" | "object" | "array";
+  type?: SchemaType;
   allOf?: (SchemaObject | ReferenceObject)[];
   oneOf?: (SchemaObject | ReferenceObject)[];
   anyOf?: (SchemaObject | ReferenceObject)[];
   not?: SchemaObject | ReferenceObject;
   items?: SchemaObject | ReferenceObject;
-  properties?: Map<SchemaObject | ReferenceObject>;
+  properties?: Record<string, SchemaObject | ReferenceObject>;
   additionalProperties?: boolean | SchemaObject | ReferenceObject;
 
   // OpenAPI additions
@@ -393,7 +396,7 @@ export type SchemaObjectWithRef = Omit<
 
 export interface DiscriminatorObject {
   propertyName: string;
-  mapping?: Map<string>;
+  mapping?: Record<string, string>;
 }
 
 export interface XMLObject {
@@ -449,7 +452,7 @@ export interface OAuthFlowObject {
   authorizationUrl?: string; // required for some
   tokenUrl?: string; // required for some
   refreshUrl?: string;
-  scopes: Map<string>;
+  scopes: Record<string, string>;
 }
 
-export type SecurityRequirementObject = Map<string[]>;
+export type SecurityRequirementObject = Record<string, string[]>;

package/src/openapi/utils/types.ts

@@ -89,6 +89,7 @@ export interface OpenAPIOperation {
   servers?: OpenAPIServer[];
   "x-codeSamples"?: OpenAPIXCodeSample[];
   "x-code-samples"?: OpenAPIXCodeSample[]; // deprecated
+  "x-position"?: number;
 }
 
 export interface OpenAPIParameter {

package/src/options.ts

@@ -39,6 +39,9 @@ export const OptionsSchema = Joi.object({
         proxy: Joi.string(),
         outputDir: Joi.string().required(),
         template: Joi.string(),
+        infoTemplate: Joi.string(),
+        tagTemplate: Joi.string(),
+        schemaTemplate: Joi.string(),
         downloadUrl: Joi.string(),
         hideSendButton: Joi.boolean(),
         showExtensions: Joi.boolean(),

package/src/plugin-openapi.d.ts

@@ -5,10 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import type { TOCItem } from "@docusaurus/mdx-loader";
+import type { VersionBanner } from "@docusaurus/plugin-content-docs";
 import type { FrontMatter as DocsFrontMatter } from "@docusaurus/types";
 import type { Props as DocsProps } from "@docusaurus/types";
 
-// TODO: figure out how to import this
 declare module "docusaurus-plugin-openapi-docs" {
   import type { PropSidebars } from "@docusaurus/plugin-content-docs-types";
 
@@ -77,7 +78,7 @@ declare module "@theme/ApiItem" {
       readonly frontMatter: FrontMatter;
       readonly metadata: Metadata;
       readonly contentTitle: string | undefined;
-      readonly toc: array | undefined;
+      readonly toc: readonly TOCItem[] | undefined;
       (): JSX.Element;
     };
   }

package/src/types.ts

@@ -6,7 +6,7 @@
  * ========================================================================== */
 
 import { SidebarItemDoc } from "@docusaurus/plugin-content-docs/src/sidebars/types";
-import type Request from "postman-collection";
+import Request from "postman-collection";
 
 import {
   InfoObject,
@@ -35,6 +35,9 @@ export interface APIOptions {
   specPath: string;
   outputDir: string;
   template?: string;
+  infoTemplate?: string;
+  tagTemplate?: string;
+  schemaTemplate?: string;
   downloadUrl?: string;
   hideSendButton?: boolean;
   showExtensions?: boolean;
@@ -115,6 +118,7 @@ export interface ApiMetadataBase {
   frontMatter: Record<string, unknown>;
   method?: string;
   path?: string;
+  position?: number;
 }
 
 export interface ApiPageMetadata extends ApiMetadataBase {

package/src/postman-collection.d.ts

@@ -1,10 +0,0 @@
-/* ============================================================================
- * 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.
- * ========================================================================== */
-
-declare module "postman-collection" {
-  export default any;
-}