@schmock/openapi 1.2.1 → 1.4.0

package/src/parser.ts

@@ -1,4 +1,4 @@
-/// <reference path="../../../types/schmock.d.ts" />
+/// <reference path="../../core/schmock.d.ts" />
 
 import SwaggerParser from "@apidevtools/swagger-parser";
 import { toHttpMethod } from "@schmock/core";
@@ -7,11 +7,40 @@ import type { OpenAPI } from "openapi-types";
 import { normalizeSchema } from "./normalizer.js";
 import { isRecord } from "./utils.js";
 
+export interface SecurityScheme {
+  type: "apiKey" | "http" | "oauth2" | "openIdConnect";
+  /** For apiKey: header, query, or cookie */
+  in?: "header" | "query" | "cookie";
+  /** For apiKey: the header/query/cookie name */
+  name?: string;
+  /** For http: bearer, basic, etc. */
+  scheme?: string;
+}
+
 export interface ParsedSpec {
   title: string;
   version: string;
   basePath: string;
   paths: ParsedPath[];
+  securitySchemes?: Map<string, SecurityScheme>;
+  globalSecurity?: string[][];
+}
+
+export interface ParsedResponseEntry {
+  schema?: JSONSchema7;
+  description: string;
+  headers?: Record<string, Schmock.ResponseHeaderDef>;
+  examples?: Map<string, unknown>;
+  contentTypes?: string[];
+}
+
+export interface ParsedCallback {
+  /** Runtime expression for the callback URL (e.g. "{$request.body#/callbackUrl}") */
+  urlExpression: string;
+  /** HTTP method for the callback request */
+  method: Schmock.HttpMethod;
+  /** JSON Schema for the callback request body */
+  requestBody?: JSONSchema7;
 }
 
 export interface ParsedPath {
@@ -21,8 +50,12 @@ export interface ParsedPath {
   operationId?: string;
   parameters: ParsedParameter[];
   requestBody?: JSONSchema7;
-  responses: Map<number, { schema?: JSONSchema7; description: string }>;
+  responses: Map<number, ParsedResponseEntry>;
   tags: string[];
+  /** Per-operation security requirements (each entry is OR, keys within are AND) */
+  security?: string[][];
+  /** OAS3 callbacks defined on this operation */
+  callbacks?: ParsedCallback[];
 }
 
 export interface ParsedParameter {
@@ -127,12 +160,19 @@ export async function parseSpec(source: string | object): Promise<ParsedSpec> {
     basePath = basePath.slice(0, -1);
   }
 
+  // Extract security schemes
+  const securitySchemes = extractSecuritySchemes(api, isSwagger2);
+  const globalSecurityRaw = "security" in api ? api.security : undefined;
+  const globalSecurity = extractSecurityRequirements(
+    Array.isArray(globalSecurityRaw) ? globalSecurityRaw : undefined,
+  );
+
   const paths: ParsedPath[] = [];
   const rawPaths =
     "paths" in api && isRecord(api.paths) ? api.paths : undefined;
 
   if (!rawPaths) {
-    return { title, version, basePath, paths };
+    return { title, version, basePath, paths, securitySchemes, globalSecurity };
   }
 
   for (const [pathTemplate, pathItemRaw] of Object.entries(rawPaths)) {
@@ -183,6 +223,17 @@ export async function parseSpec(source: string | object): Promise<ParsedSpec> {
         ? operation.tags.filter((t): t is string => typeof t === "string")
         : [];
 
+      // Extract per-operation security
+      const operationSecurity = Array.isArray(operation.security)
+        ? extractSecurityRequirements(operation.security)
+        : undefined;
+
+      // Extract OAS3 callbacks
+      const callbacks =
+        !isSwagger2 && isRecord(operation.callbacks)
+          ? extractCallbacks(operation.callbacks)
+          : undefined;
+
       // Filter out body parameters from the final parameter list (Swagger 2.0)
       const filteredParams = mergedParams.filter(isNotBodyParam);
 
@@ -194,11 +245,13 @@ export async function parseSpec(source: string | object): Promise<ParsedSpec> {
         requestBody,
         responses,
         tags,
+        security: operationSecurity,
+        callbacks,
       });
     }
   }
 
-  return { title, version, basePath, paths };
+  return { title, version, basePath, paths, securitySchemes, globalSecurity };
 }
 
 interface InternalParameter {
@@ -318,11 +371,8 @@ function extractOpenApi3RequestBody(
 function extractResponses(
   responses: Record<string, unknown> | undefined,
   isSwagger2: boolean,
-): Map<number, { schema?: JSONSchema7; description: string }> {
-  const result = new Map<
-    number,
-    { schema?: JSONSchema7; description: string }
-  >();
+): Map<number, ParsedResponseEntry> {
+  const result = new Map<number, ParsedResponseEntry>();
 
   if (!responses) return result;
 
@@ -336,28 +386,106 @@ function extractResponses(
     const description = getString(response.description) ?? "";
 
     let schema: JSONSchema7 | undefined;
+    let examples: Map<string, unknown> | undefined;
+    let contentTypes: string[] | undefined;
+
     if (isSwagger2) {
-      // Swagger 2.0: schema is directly on the response
       if (isRecord(response.schema)) {
         schema = normalizeSchema(response.schema, "response");
       }
+      // Swagger 2.0 single example
+      if (response.examples !== undefined && isRecord(response.examples)) {
+        examples = new Map();
+        for (const [key, value] of Object.entries(response.examples)) {
+          examples.set(key, value);
+        }
+      }
     } else {
-      // OpenAPI 3.x: schema is nested in content
       const content = isRecord(response.content) ? response.content : undefined;
       if (content) {
+        contentTypes = Object.keys(content);
         const jsonEntry = findJsonContent(content);
         if (jsonEntry && isRecord(jsonEntry.schema)) {
           schema = normalizeSchema(jsonEntry.schema, "response");
         }
+        // OAS3 named examples
+        if (jsonEntry) {
+          examples = extractExamples(jsonEntry);
+        }
       }
     }
 
-    result.set(code, { schema, description });
+    const headers = extractResponseHeaders(response, isSwagger2);
+    result.set(code, { schema, description, headers, examples, contentTypes });
   }
 
   return result;
 }
 
+function extractExamples(
+  contentEntry: Record<string, unknown>,
+): Map<string, unknown> | undefined {
+  const result = new Map<string, unknown>();
+
+  // Single `example` value
+  if ("example" in contentEntry && contentEntry.example !== undefined) {
+    result.set("default", contentEntry.example);
+  }
+
+  // Named `examples` map
+  if (isRecord(contentEntry.examples)) {
+    for (const [name, exampleObj] of Object.entries(contentEntry.examples)) {
+      if (isRecord(exampleObj) && "value" in exampleObj) {
+        result.set(name, exampleObj.value);
+      }
+    }
+  }
+
+  return result.size > 0 ? result : undefined;
+}
+
+function extractResponseHeaders(
+  response: Record<string, unknown>,
+  isSwagger2: boolean,
+): Record<string, Schmock.ResponseHeaderDef> | undefined {
+  const rawHeaders = isRecord(response.headers) ? response.headers : undefined;
+  if (!rawHeaders) return undefined;
+
+  const headers: Record<string, Schmock.ResponseHeaderDef> = {};
+  let hasHeaders = false;
+
+  for (const [name, headerRaw] of Object.entries(rawHeaders)) {
+    if (!isRecord(headerRaw)) continue;
+
+    const desc = getString(headerRaw.description) ?? "";
+    let headerSchema: JSONSchema7 | undefined;
+
+    if (isSwagger2) {
+      // Swagger 2.0: type/format/enum are inline on the header
+      if (headerRaw.type) {
+        headerSchema = normalizeSchema(
+          {
+            type: headerRaw.type,
+            format: headerRaw.format,
+            enum: headerRaw.enum,
+          },
+          "response",
+        );
+      }
+    } else {
+      // OpenAPI 3.x: schema is nested
+      if (isRecord(headerRaw.schema)) {
+        headerSchema = normalizeSchema(headerRaw.schema, "response");
+      }
+    }
+
+    headers[name] = { schema: headerSchema, description: desc };
+    hasHeaders = true;
+  }
+
+  return hasHeaders ? headers : undefined;
+}
+
 /**
  * Find the best JSON-like content type entry from an OpenAPI content map.
  * Prefers application/json, then any *+json or *json* type.
@@ -384,3 +512,155 @@ function findJsonContent(
 function convertPathTemplate(path: string): string {
   return path.replace(/\{([^}]+)\}/g, ":$1");
 }
+
+function extractSecuritySchemes(
+  api: OpenAPI.Document,
+  isSwagger2: boolean,
+): Map<string, SecurityScheme> | undefined {
+  const schemes = new Map<string, SecurityScheme>();
+
+  let rawSchemes: Record<string, unknown> | undefined;
+
+  if (isSwagger2) {
+    // Swagger 2.0: securityDefinitions
+    if ("securityDefinitions" in api) {
+      const defs = api.securityDefinitions;
+      if (isRecord(defs)) {
+        rawSchemes = defs;
+      }
+    }
+  } else {
+    // OpenAPI 3.x: components.securitySchemes
+    if ("components" in api && isRecord(api.components)) {
+      const comp = api.components;
+      if ("securitySchemes" in comp && isRecord(comp.securitySchemes)) {
+        rawSchemes = comp.securitySchemes;
+      }
+    }
+  }
+
+  if (!rawSchemes) return schemes.size > 0 ? schemes : undefined;
+
+  for (const [name, schemeDef] of Object.entries(rawSchemes)) {
+    if (!isRecord(schemeDef)) continue;
+
+    const type = getString(schemeDef.type);
+    if (!type) continue;
+
+    const scheme = toSecurityScheme(type, schemeDef, isSwagger2);
+    if (scheme) {
+      schemes.set(name, scheme);
+    }
+  }
+
+  return schemes.size > 0 ? schemes : undefined;
+}
+
+const SECURITY_SCHEME_TYPES = new Set([
+  "apiKey",
+  "http",
+  "oauth2",
+  "openIdConnect",
+]);
+const API_KEY_LOCATIONS = new Set(["header", "query", "cookie"]);
+
+function toSecurityScheme(
+  type: string,
+  def: Record<string, unknown>,
+  isSwagger2: boolean,
+): SecurityScheme | undefined {
+  // Handle Swagger 2.0 basic auth
+  if (isSwagger2 && type === "basic") {
+    return { type: "http", scheme: "basic" };
+  }
+
+  if (!SECURITY_SCHEME_TYPES.has(type)) return undefined;
+
+  const scheme: SecurityScheme = {
+    type:
+      type === "apiKey"
+        ? "apiKey"
+        : type === "http"
+          ? "http"
+          : type === "oauth2"
+            ? "oauth2"
+            : "openIdConnect",
+  };
+
+  if (type === "apiKey") {
+    const location = getString(def.in);
+    if (location && API_KEY_LOCATIONS.has(location)) {
+      scheme.in =
+        location === "header"
+          ? "header"
+          : location === "query"
+            ? "query"
+            : "cookie";
+    }
+    scheme.name = getString(def.name);
+  } else if (type === "http") {
+    scheme.scheme = getString(def.scheme);
+  }
+
+  return scheme;
+}
+
+/**
+ * Extract security requirements from a security array.
+ * Each entry in the array is an OR condition (any can match).
+ * Each entry is an object where keys are scheme names (AND within).
+ * Returns array of string arrays: [[schemeA, schemeB], [schemeC]] means (A AND B) OR C.
+ * An empty array entry means "no auth required" (public).
+ */
+function extractSecurityRequirements(
+  security: unknown[] | undefined,
+): string[][] | undefined {
+  if (!security || security.length === 0) return undefined;
+
+  const result: string[][] = [];
+  for (const entry of security) {
+    if (!isRecord(entry)) continue;
+    result.push(Object.keys(entry));
+  }
+
+  return result.length > 0 ? result : undefined;
+}
+
+/**
+ * Extract OAS3 callbacks from an operation.
+ * Callbacks structure: { callbackName: { urlExpression: { method: { requestBody, ... } } } }
+ */
+function extractCallbacks(
+  callbacks: Record<string, unknown>,
+): ParsedCallback[] | undefined {
+  const result: ParsedCallback[] = [];
+
+  for (const callbackObj of Object.values(callbacks)) {
+    if (!isRecord(callbackObj)) continue;
+
+    // Each key is a URL expression like "{$request.body#/callbackUrl}"
+    for (const [urlExpression, pathItem] of Object.entries(callbackObj)) {
+      if (!isRecord(pathItem)) continue;
+
+      for (const methodKey of Object.keys(pathItem)) {
+        if (!HTTP_METHOD_KEYS.has(methodKey)) continue;
+
+        const operation = pathItem[methodKey];
+        if (!isRecord(operation)) continue;
+
+        let reqBody: JSONSchema7 | undefined;
+        if (isRecord(operation.requestBody)) {
+          reqBody = extractOpenApi3RequestBody(operation.requestBody);
+        }
+
+        result.push({
+          urlExpression,
+          method: toHttpMethod(methodKey.toUpperCase()),
+          requestBody: reqBody,
+        });
+      }
+    }
+  }
+
+  return result.length > 0 ? result : undefined;
+}