@camunda8/docusaurus-plugin-openapi-docs 4.5.1

package/src/openapi/sdkExamples.ts

@@ -0,0 +1,195 @@
+/* ============================================================================
+ * 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 path from "path";
+
+import fs from "fs-extra";
+
+/**
+ * Configuration for a single SDK example source.
+ */
+export interface SdkExampleSource {
+  /** Language label shown in the code sample tab (e.g. "TypeScript", "Python", "C#"). */
+  lang: string;
+  /** Syntax highlight mode (e.g. "typescript", "python", "csharp"). */
+  highlight?: string;
+  /** Path to the operation-map.json file (relative to site root or absolute). */
+  operationMapPath: string;
+}
+
+/**
+ * A single entry in operation-map.json for one operationId.
+ */
+interface OperationMapEntry {
+  file: string;
+  region: string;
+  label?: string;
+}
+
+/**
+ * Shape of operation-map.json: operationId -> entries[].
+ */
+type OperationMap = Record<string, OperationMapEntry[]>;
+
+// Region marker patterns for supported languages.
+// Each pattern matches the start/end of a named region.
+const REGION_PATTERNS: {
+  start: RegExp;
+  end: RegExp;
+}[] = [
+  // TypeScript/JavaScript: //#region Name  ...  //#endregion [Name]
+  {
+    start: /^\s*\/\/#region\s+(.+?)\s*$/,
+    end: /^\s*\/\/#endregion(?:\s+(.+?))?\s*$/,
+  },
+  // C#: #region Name  ...  #endregion [Name]
+  {
+    start: /^\s*#region\s+(.+?)\s*$/,
+    end: /^\s*#endregion(?:\s+(.+?))?\s*$/,
+  },
+  // XML-style: // <RegionName>  ...  // </RegionName>
+  {
+    start: /^\s*\/\/\s*<([A-Za-z]\w*)>\s*$/,
+    end: /^\s*\/\/\s*<\/([A-Za-z]\w*)>\s*$/,
+  },
+  // Python: # region Name  ...  # endregion [Name]
+  {
+    start: /^\s*#\s*region\s+(.+?)\s*$/,
+    end: /^\s*#\s*endregion(?:\s+(.+?))?\s*$/,
+  },
+];
+
+/**
+ * Extract the code between region markers from a source file's content.
+ * Returns the trimmed code block or undefined if the region is not found.
+ */
+function extractRegion(
+  content: string,
+  regionName: string
+): string | undefined {
+  const lines = content.split(/\r?\n/);
+  let capturing = false;
+  let capturedLines: string[] = [];
+
+  for (const line of lines) {
+    if (capturing) {
+      // Check if this line is an end marker for our region
+      for (const pattern of REGION_PATTERNS) {
+        const endMatch = line.match(pattern.end);
+        if (
+          endMatch &&
+          (!endMatch[1] || endMatch[1].trim() === regionName)
+        ) {
+          // Found end marker — return captured content
+          return trimIndentation(capturedLines);
+        }
+      }
+      capturedLines.push(line);
+    } else {
+      // Check if this line is a start marker for our region
+      for (const pattern of REGION_PATTERNS) {
+        const startMatch = line.match(pattern.start);
+        if (startMatch && startMatch[1].trim() === regionName) {
+          capturing = true;
+          capturedLines = [];
+          break;
+        }
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Remove the common leading whitespace from all non-empty lines.
+ */
+function trimIndentation(lines: string[]): string {
+  const nonEmptyLines = lines.filter((l) => l.trim().length > 0);
+  if (nonEmptyLines.length === 0) return "";
+
+  const minIndent = Math.min(
+    ...nonEmptyLines.map((l) => {
+      const match = l.match(/^(\s*)/);
+      return match ? match[1].length : 0;
+    })
+  );
+
+  return lines
+    .map((l) => (l.trim().length === 0 ? "" : l.slice(minIndent)))
+    .join("\n")
+    .trim();
+}
+
+/**
+ * Build x-codeSamples entries for a given operationId from all configured SDK sources.
+ *
+ * @param operationId - The OpenAPI operationId to look up.
+ * @param sdkExamples - Array of SDK example source configurations.
+ * @param siteDir - The Docusaurus site root directory (for resolving relative paths).
+ * @param fileCache - Shared cache to avoid re-reading the same source files.
+ * @param mapCache - Shared cache for parsed operation-map.json files.
+ * @returns Array of x-codeSamples entries, or empty array if none found.
+ */
+export function buildCodeSamples(
+  operationId: string,
+  sdkExamples: SdkExampleSource[],
+  siteDir: string,
+  fileCache: Map<string, string>,
+  mapCache: Map<string, OperationMap>
+): { lang: string; label: string; source: string }[] {
+  const samples: { lang: string; label: string; source: string }[] = [];
+
+  for (const sdk of sdkExamples) {
+    const mapPath = path.resolve(siteDir, sdk.operationMapPath);
+    let operationMap = mapCache.get(mapPath);
+    if (!operationMap) {
+      if (!fs.existsSync(mapPath)) {
+        console.warn(`SDK examples: operation-map not found at ${mapPath}`);
+        continue;
+      }
+      operationMap = fs.readJSONSync(mapPath) as OperationMap;
+      mapCache.set(mapPath, operationMap);
+    }
+
+    const entries = operationMap[operationId];
+    if (!entries || entries.length === 0) continue;
+
+    const mapDir = path.dirname(mapPath);
+
+    for (const entry of entries) {
+      const filePath = path.resolve(mapDir, entry.file);
+      let fileContent = fileCache.get(filePath);
+      if (fileContent === undefined) {
+        if (!fs.existsSync(filePath)) {
+          console.warn(
+            `SDK examples: source file not found at ${filePath} (referenced by ${sdk.lang} operation-map for ${operationId})`
+          );
+          continue;
+        }
+        fileContent = fs.readFileSync(filePath, "utf-8");
+        fileCache.set(filePath, fileContent);
+      }
+
+      const code = extractRegion(fileContent, entry.region);
+      if (!code) {
+        console.warn(
+          `SDK examples: region "${entry.region}" not found in ${filePath} (${sdk.lang}, ${operationId})`
+        );
+        continue;
+      }
+
+      samples.push({
+        lang: sdk.lang,
+        label: "SDK",
+        source: code,
+      });
+    }
+  }
+
+  return samples;
+}

package/src/openapi/types.ts

@@ -0,0 +1,458 @@
+/* ============================================================================
+ * 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 type {
+  JSONSchema4,
+  JSONSchema6,
+  JSONSchema7,
+  JSONSchema7TypeName,
+} from "json-schema";
+
+export interface OpenApiObject {
+  openapi: string;
+  info: InfoObject;
+  servers?: ServerObject[];
+  paths: PathsObject;
+  components?: ComponentsObject;
+  security?: SecurityRequirementObject[];
+  tags?: TagObject[];
+  externalDocs?: ExternalDocumentationObject;
+  swagger?: string;
+  webhooks?: PathsObject;
+  "x-webhooks"?: PathsObject;
+  "x-tagGroups"?: TagGroupObject[];
+}
+
+export interface OpenApiObjectWithRef {
+  openapi: string;
+  info: InfoObject;
+  servers?: ServerObject[];
+  paths: PathsObjectWithRef;
+  components?: ComponentsObjectWithRef;
+  security?: SecurityRequirementObject[];
+  tags?: TagObject[];
+  externalDocs?: ExternalDocumentationObject;
+}
+
+export interface InfoObject {
+  title: string;
+  description?: string;
+  termsOfService?: string;
+  contact?: ContactObject;
+  license?: LicenseObject;
+  version: string;
+  tags?: TagObject[];
+  "x-logo"?: LogoObject;
+  "x-dark-logo"?: LogoObject;
+  logo?: LogoObject;
+  darkLogo?: LogoObject;
+}
+
+export interface LogoObject {
+  url?: string;
+}
+
+export interface ContactObject {
+  name?: string;
+  url?: string;
+  email?: string;
+}
+
+export interface LicenseObject {
+  name: string;
+  url?: string;
+}
+
+export interface ServerObject {
+  url: string;
+  description?: string;
+  variables?: Record<string, ServerVariable>;
+}
+
+export interface ServerVariable {
+  enum?: string[];
+  default: string;
+  description?: string;
+}
+
+export interface ComponentsObject {
+  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?: 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 = Record<string, PathItemObject>;
+
+export type PathsObjectWithRef = Record<string, PathItemObjectWithRef>;
+
+export interface PathItemObject {
+  $ref?: string;
+  summary?: string;
+  description?: string;
+  get?: OperationObject;
+  put?: OperationObject;
+  post?: OperationObject;
+  delete?: OperationObject;
+  options?: OperationObject;
+  head?: OperationObject;
+  patch?: OperationObject;
+  trace?: OperationObject;
+  servers?: ServerObject[];
+  parameters?: ParameterObject[];
+}
+
+export interface PathItemObjectWithRef {
+  $ref?: string;
+  summary?: string;
+  description?: string;
+  get?: OperationObjectWithRef;
+  put?: OperationObjectWithRef;
+  post?: OperationObjectWithRef;
+  delete?: OperationObjectWithRef;
+  options?: OperationObjectWithRef;
+  head?: OperationObjectWithRef;
+  patch?: OperationObjectWithRef;
+  trace?: OperationObjectWithRef;
+  servers?: ServerObject[];
+  parameters?: (ParameterObjectWithRef | ReferenceObject)[];
+}
+
+export interface OperationObject {
+  tags?: string[];
+  summary?: string;
+  description?: string;
+  externalDocs?: ExternalDocumentationObject;
+  operationId?: string;
+  parameters?: ParameterObject[];
+  requestBody?: RequestBodyObject;
+  responses: ResponsesObject;
+  callbacks?: Record<string, CallbackObject>;
+  deprecated?: boolean;
+  security?: SecurityRequirementObject[];
+  servers?: ServerObject[];
+  // extensions
+  "x-position"?: number;
+  "x-deprecated-description"?: string;
+}
+
+export interface OperationObjectWithRef {
+  tags?: string[];
+  summary?: string;
+  description?: string;
+  externalDocs?: ExternalDocumentationObject;
+  operationId?: string;
+  parameters?: (ParameterObjectWithRef | ReferenceObject)[];
+  requestBody?: RequestBodyObjectWithRef | ReferenceObject;
+  responses: ResponsesObjectWithRef;
+  callbacks?: Record<string, CallbackObjectWithRef | ReferenceObject>;
+  deprecated?: boolean;
+  security?: SecurityRequirementObject[];
+  servers?: ServerObject[];
+
+  // extensions
+  "x-deprecated-description"?: string;
+}
+
+export interface ExternalDocumentationObject {
+  description?: string;
+  url: string;
+}
+
+export interface ParameterObject {
+  name: string;
+  in: "query" | "header" | "path" | "cookie";
+  description?: string;
+  required?: boolean;
+  deprecated?: boolean;
+  allowEmptyValue?: boolean;
+  //
+  style?: string;
+  explode?: string;
+  allowReserved?: boolean;
+  schema?: SchemaObject;
+  example?: any;
+  examples?: Record<string, ExampleObject>;
+  //
+  content?: Record<string, MediaTypeObject>;
+  param?: Object;
+  // ignoring stylings: matrix, label, form, simple, spaceDelimited,
+  // pipeDelimited and deepObject
+  "x-enumDescriptions"?: Record<string, string>;
+}
+
+export interface ParameterObjectWithRef {
+  name: string;
+  in: string;
+  description?: string;
+  required?: boolean;
+  deprecated?: boolean;
+  allowEmptyValue?: boolean;
+  //
+  style?: string;
+  explode?: string;
+  allowReserved?: boolean;
+  schema?: SchemaObjectWithRef | ReferenceObject;
+  example?: any;
+  examples?: Record<string, ExampleObject | ReferenceObject>;
+  //
+  content?: Record<string, MediaTypeObjectWithRef>;
+  // ignoring stylings: matrix, label, form, simple, spaceDelimited,
+  // pipeDelimited and deepObject
+}
+
+export interface RequestBodyObject {
+  description?: string;
+  content: Record<string, MediaTypeObject>;
+  required?: boolean;
+}
+
+export interface RequestBodyObjectWithRef {
+  description?: string;
+  content: Record<string, MediaTypeObjectWithRef>;
+  required?: boolean;
+}
+
+export interface MediaTypeObject {
+  schema?: SchemaObject;
+  example?: any;
+  examples?: Record<string, ExampleObject>;
+  encoding?: Record<string, EncodingObject>;
+  type?: any;
+}
+
+export interface MediaTypeObjectWithRef {
+  schema?: SchemaObjectWithRef | ReferenceObject;
+  example?: any;
+  examples?: Record<string, ExampleObject | ReferenceObject>;
+  encoding?: Record<string, EncodingObjectWithRef>;
+}
+
+export interface EncodingObject {
+  contentType?: string;
+  headers?: Record<string, HeaderObject>;
+  style?: string;
+  explode?: boolean;
+  allowReserved?: boolean;
+}
+
+export interface EncodingObjectWithRef {
+  contentType?: string;
+  headers?: Record<string, HeaderObjectWithRef | ReferenceObject>;
+  style?: string;
+  explode?: boolean;
+  allowReserved?: boolean;
+}
+
+export type ResponsesObject = Record<string, ResponseObject>;
+
+export type ResponsesObjectWithRef = Record<
+  string,
+  ResponseObjectWithRef | ReferenceObject
+>;
+
+export interface ResponseObject {
+  description: string;
+  headers?: Record<string, HeaderObject>;
+  content?: Record<string, MediaTypeObject>;
+  links?: Record<string, LinkObject>;
+}
+
+export interface ResponseObjectWithRef {
+  description: string;
+  headers?: Record<string, HeaderObjectWithRef | ReferenceObject>;
+  content?: Record<string, MediaTypeObjectWithRef>;
+  links?: Record<string, LinkObject | ReferenceObject>;
+}
+
+export type CallbackObject = Record<string, PathItemObject>;
+
+export type CallbackObjectWithRef = Record<string, PathItemObjectWithRef>;
+
+export interface ExampleObject {
+  summary?: string;
+  description?: string;
+  value?: any;
+  externalValue?: string;
+}
+
+export interface LinkObject {
+  operationRef?: string;
+  operationId?: string;
+  parameters?: Record<string, any>;
+  requestBody?: any;
+  description?: string;
+  server?: ServerObject;
+}
+
+export type HeaderObject = Omit<ParameterObject, "name" | "in">;
+
+export type HeaderObjectWithRef = Omit<ParameterObjectWithRef, "name" | "in">;
+
+export interface TagObject {
+  name?: string;
+  description?: string;
+  externalDocs?: ExternalDocumentationObject;
+  "x-displayName"?: string;
+}
+
+export interface TagGroupObject {
+  name: string;
+  tags: string[];
+}
+
+export interface ReferenceObject {
+  $ref: string;
+}
+
+export type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
+export type SchemaType = JSONSchema7TypeName;
+export type SchemaObject = Omit<
+  JSONSchema,
+  | "type"
+  | "allOf"
+  | "oneOf"
+  | "anyOf"
+  | "not"
+  | "items"
+  | "properties"
+  | "additionalProperties"
+> & {
+  // OpenAPI specific overrides
+  type?: SchemaType;
+  allOf?: SchemaObject[];
+  oneOf?: SchemaObject[];
+  anyOf?: SchemaObject[];
+  not?: SchemaObject;
+  items?: SchemaObject;
+  properties?: Record<string, SchemaObject>;
+  additionalProperties?: boolean | SchemaObject;
+
+  // OpenAPI additions
+  nullable?: boolean;
+  discriminator?: DiscriminatorObject;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  xml?: XMLObject;
+  externalDocs?: ExternalDocumentationObject;
+  example?: any;
+  deprecated?: boolean;
+  "x-tags"?: string[];
+  "x-enumDescriptions"?: Record<string, string>;
+};
+
+export type SchemaObjectWithRef = Omit<
+  JSONSchema,
+  | "type"
+  | "allOf"
+  | "oneOf"
+  | "anyOf"
+  | "not"
+  | "items"
+  | "properties"
+  | "additionalProperties"
+> & {
+  // OpenAPI specific overrides
+  type?: SchemaType;
+  allOf?: (SchemaObject | ReferenceObject)[];
+  oneOf?: (SchemaObject | ReferenceObject)[];
+  anyOf?: (SchemaObject | ReferenceObject)[];
+  not?: SchemaObject | ReferenceObject;
+  items?: SchemaObject | ReferenceObject;
+  properties?: Record<string, SchemaObject | ReferenceObject>;
+  additionalProperties?: boolean | SchemaObject | ReferenceObject;
+
+  // OpenAPI additions
+  nullable?: boolean;
+  discriminator?: DiscriminatorObject;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  xml?: XMLObject;
+  externalDocs?: ExternalDocumentationObject;
+  example?: any;
+  deprecated?: boolean;
+};
+
+export interface DiscriminatorObject {
+  propertyName: string;
+  mapping?: Record<string, string>;
+}
+
+export interface XMLObject {
+  name?: string;
+  namespace?: string;
+  prefix?: string;
+  attribute?: boolean;
+  wrapped?: boolean;
+}
+
+export type SecuritySchemeObject =
+  | ApiKeySecuritySchemeObject
+  | HttpSecuritySchemeObject
+  | Oauth2SecuritySchemeObject
+  | OpenIdConnectSecuritySchemeObject;
+
+export interface ApiKeySecuritySchemeObject {
+  type: "apiKey";
+  description?: string;
+  name: string;
+  in: "query" | "header" | "cookie";
+}
+
+export interface HttpSecuritySchemeObject {
+  type: "http";
+  description?: string;
+  scheme: string;
+  bearerFormat?: string;
+  name?: string;
+  in?: string;
+}
+
+export interface Oauth2SecuritySchemeObject {
+  type: "oauth2";
+  description?: string;
+  flows: OAuthFlowsObject;
+}
+
+export interface OpenIdConnectSecuritySchemeObject {
+  type: "openIdConnect";
+  description?: string;
+  openIdConnectUrl: string;
+}
+
+export interface OAuthFlowsObject {
+  implicit?: OAuthFlowObject;
+  password?: OAuthFlowObject;
+  clientCredentials?: OAuthFlowObject;
+  authorizationCode?: OAuthFlowObject;
+}
+
+export interface OAuthFlowObject {
+  authorizationUrl?: string; // required for some
+  tokenUrl?: string; // required for some
+  refreshUrl?: string;
+  scopes: Record<string, string>;
+}
+
+export type SecurityRequirementObject = Record<string, string[]>;