@schmock/openapi 1.1.0

package/dist/normalizer.d.ts

@@ -0,0 +1,14 @@
+import type { JSONSchema7 } from "json-schema";
+/**
+ * Normalize an OpenAPI schema to pure JSON Schema 7 that json-schema-faker understands.
+ *
+ * Transforms applied:
+ * - nullable: true -> oneOf with null type
+ * - discriminator -> required + enum on branches
+ * - readOnly/writeOnly -> strip based on direction
+ * - example -> default (if default not set)
+ * - exclusiveMinimum/exclusiveMaximum boolean -> number format
+ * - x-* extensions -> stripped
+ */
+export declare function normalizeSchema(schema: Record<string, unknown>, direction: "request" | "response"): JSONSchema7;
+//# sourceMappingURL=normalizer.d.ts.map

package/dist/normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizer.d.ts","sourceRoot":"","sources":["../src/normalizer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAa/C;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,SAAS,GAAG,UAAU,GAChC,WAAW,CAEb"}

package/dist/normalizer.js

@@ -0,0 +1,194 @@
+/// <reference path="../../../types/schmock.d.ts" />
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toJsonSchema(node) {
+    // Object.assign merges unknown-keyed properties into JSONSchema7.
+    // This is safe because the normalizer has already ensured the shape
+    // is valid JSON Schema 7 before calling this function.
+    return Object.assign({}, node);
+}
+/**
+ * Normalize an OpenAPI schema to pure JSON Schema 7 that json-schema-faker understands.
+ *
+ * Transforms applied:
+ * - nullable: true -> oneOf with null type
+ * - discriminator -> required + enum on branches
+ * - readOnly/writeOnly -> strip based on direction
+ * - example -> default (if default not set)
+ * - exclusiveMinimum/exclusiveMaximum boolean -> number format
+ * - x-* extensions -> stripped
+ */
+export function normalizeSchema(schema, direction) {
+    return normalizeNode(structuredClone(schema), direction, new WeakSet());
+}
+function normalizeNode(node, direction, visited) {
+    if (!node || typeof node !== "object" || Array.isArray(node)) {
+        return toJsonSchema({});
+    }
+    // Circular reference detection — break cycles
+    if (visited.has(node)) {
+        return toJsonSchema({});
+    }
+    visited.add(node);
+    // Strip x-* extensions
+    for (const key of Object.keys(node)) {
+        if (key.startsWith("x-")) {
+            delete node[key];
+        }
+    }
+    // Handle nullable: true -> oneOf with null
+    if (node.nullable === true) {
+        delete node.nullable;
+        // Only wrap if not already a composition with null
+        const copy = { ...node };
+        delete copy.nullable;
+        return {
+            oneOf: [normalizeNode(copy, direction, visited), { type: "null" }],
+        };
+    }
+    delete node.nullable;
+    // Handle discriminator
+    if (node.discriminator && isRecord(node.discriminator)) {
+        const disc = node.discriminator;
+        const propName = disc.propertyName;
+        if (typeof propName === "string" && Array.isArray(node.oneOf)) {
+            const mappingRaw = disc.mapping ?? {};
+            const mapping = isRecord(mappingRaw) ? mappingRaw : {};
+            // mapping keys ARE the discriminator values (e.g. "dog", "cat")
+            // mapping values are $ref strings — after dereference they can't be matched to branches
+            // Use key order to correspond to oneOf branch order
+            const discriminatorValues = Object.keys(mapping);
+            node.oneOf = node.oneOf
+                .filter((branch) => isRecord(branch))
+                .map((branch, index) => {
+                const normalized = normalizeNode(branch, direction, visited);
+                // Ensure discriminator property is required
+                if (isRecord(normalized)) {
+                    const required = Array.isArray(normalized.required)
+                        ? [...normalized.required]
+                        : [];
+                    if (!required.includes(propName)) {
+                        required.push(propName);
+                    }
+                    normalized.required = required;
+                    // Add enum constraint for the discriminator value
+                    const mappingValue = discriminatorValues[index];
+                    if (mappingValue && isRecord(normalized.properties)) {
+                        const props = normalized.properties;
+                        const existingRaw = props[propName] ?? {};
+                        const existing = isRecord(existingRaw) ? existingRaw : {};
+                        props[propName] = { ...existing, enum: [mappingValue] };
+                    }
+                }
+                return normalized;
+            });
+        }
+        delete node.discriminator;
+    }
+    // Handle readOnly/writeOnly on properties
+    if (isRecord(node.properties)) {
+        const props = node.properties;
+        const required = Array.isArray(node.required)
+            ? node.required.filter((r) => typeof r === "string")
+            : [];
+        const keysToRemove = [];
+        for (const [propName, propSchemaRaw] of Object.entries(props)) {
+            if (!isRecord(propSchemaRaw))
+                continue;
+            const propSchema = propSchemaRaw;
+            // readOnly fields: remove from request schemas
+            if (direction === "request" && propSchema.readOnly === true) {
+                keysToRemove.push(propName);
+                continue;
+            }
+            // writeOnly fields: remove from response schemas
+            if (direction === "response" && propSchema.writeOnly === true) {
+                keysToRemove.push(propName);
+                continue;
+            }
+            // Clean up the flags after handling
+            delete propSchema.readOnly;
+            delete propSchema.writeOnly;
+            // Recurse into property
+            props[propName] = normalizeNode(propSchema, direction, visited);
+        }
+        for (const key of keysToRemove) {
+            delete props[key];
+            const reqIdx = required.indexOf(key);
+            if (reqIdx !== -1) {
+                required.splice(reqIdx, 1);
+            }
+        }
+        if (required.length > 0) {
+            node.required = required;
+        }
+        else if (keysToRemove.length > 0 && Array.isArray(node.required)) {
+            // If we removed all required fields, clean up
+            if (required.length === 0) {
+                delete node.required;
+            }
+        }
+    }
+    // Handle example -> default
+    if ("example" in node && !("default" in node)) {
+        node.default = node.example;
+    }
+    delete node.example;
+    // Handle exclusiveMinimum/exclusiveMaximum boolean -> number
+    if (node.exclusiveMinimum === true && typeof node.minimum === "number") {
+        node.exclusiveMinimum = node.minimum;
+        delete node.minimum;
+    }
+    else if (node.exclusiveMinimum === false) {
+        delete node.exclusiveMinimum;
+    }
+    if (node.exclusiveMaximum === true && typeof node.maximum === "number") {
+        node.exclusiveMaximum = node.maximum;
+        delete node.maximum;
+    }
+    else if (node.exclusiveMaximum === false) {
+        delete node.exclusiveMaximum;
+    }
+    // Recurse into items (array schema)
+    if (node.items) {
+        if (Array.isArray(node.items)) {
+            node.items = node.items.map((item) => isRecord(item) ? normalizeNode(item, direction, visited) : item);
+        }
+        else if (isRecord(node.items)) {
+            node.items = normalizeNode(node.items, direction, visited);
+        }
+    }
+    // Recurse into additionalProperties
+    if (isRecord(node.additionalProperties)) {
+        node.additionalProperties = normalizeNode(node.additionalProperties, direction, visited);
+    }
+    // Recurse into composition keywords
+    for (const keyword of ["allOf", "anyOf", "oneOf"]) {
+        const keywordValue = node[keyword];
+        if (Array.isArray(keywordValue)) {
+            node[keyword] = keywordValue.map((branch) => isRecord(branch) ? normalizeNode(branch, direction, visited) : branch);
+        }
+    }
+    // Recurse into not
+    if (isRecord(node.not)) {
+        node.not = normalizeNode(node.not, direction, visited);
+    }
+    // Recurse into conditional
+    for (const keyword of ["if", "then", "else"]) {
+        const keywordValue = node[keyword];
+        if (isRecord(keywordValue)) {
+            node[keyword] = normalizeNode(keywordValue, direction, visited);
+        }
+    }
+    // Recurse into patternProperties
+    if (isRecord(node.patternProperties)) {
+        const pp = node.patternProperties;
+        for (const [pattern, schema] of Object.entries(pp)) {
+            if (isRecord(schema)) {
+                pp[pattern] = normalizeNode(schema, direction, visited);
+            }
+        }
+    }
+    return toJsonSchema(node);
+}

package/dist/parser.d.ts

@@ -0,0 +1,32 @@
+import type { JSONSchema7 } from "json-schema";
+export interface ParsedSpec {
+    title: string;
+    version: string;
+    basePath: string;
+    paths: ParsedPath[];
+}
+export interface ParsedPath {
+    /** Express-style path e.g. "/pets/:petId" */
+    path: string;
+    method: Schmock.HttpMethod;
+    operationId?: string;
+    parameters: ParsedParameter[];
+    requestBody?: JSONSchema7;
+    responses: Map<number, {
+        schema?: JSONSchema7;
+        description: string;
+    }>;
+    tags: string[];
+}
+export interface ParsedParameter {
+    name: string;
+    in: "path" | "query" | "header";
+    required: boolean;
+    schema?: JSONSchema7;
+}
+/**
+ * Parse an OpenAPI/Swagger spec into a normalized internal model.
+ * Supports Swagger 2.0, OpenAPI 3.0, and 3.1.
+ */
+export declare function parseSpec(source: string | object): Promise<ParsedSpec>;
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI/C,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtE,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAkDD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAuH5E"}

package/dist/parser.js

@@ -0,0 +1,282 @@
+/// <reference path="../../../types/schmock.d.ts" />
+import SwaggerParser from "@apidevtools/swagger-parser";
+import { toHttpMethod } from "@schmock/core";
+import { normalizeSchema } from "./normalizer.js";
+const HTTP_METHOD_KEYS = new Set([
+    "get",
+    "post",
+    "put",
+    "delete",
+    "patch",
+    "head",
+    "options",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isOpenApiDocument(value) {
+    return isRecord(value) && ("swagger" in value || "openapi" in value);
+}
+function getString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function getBoolean(value, fallback) {
+    return typeof value === "boolean" ? value : fallback;
+}
+/**
+ * Strip root-level x-* extensions from a spec object.
+ * These may contain $ref to external docs (e.g. markdown files)
+ * that swagger-parser cannot resolve.
+ */
+function stripRootExtensions(spec) {
+    for (const key of Object.keys(spec)) {
+        if (key.startsWith("x-")) {
+            Reflect.deleteProperty(spec, key);
+        }
+    }
+}
+/**
+ * Ensure a paths key exists on a spec object (required by swagger-parser validation).
+ */
+function ensurePathsKey(spec) {
+    if (!("paths" in spec)) {
+        Object.assign(spec, { paths: {} });
+    }
+}
+/**
+ * Parse an OpenAPI/Swagger spec into a normalized internal model.
+ * Supports Swagger 2.0, OpenAPI 3.0, and 3.1.
+ */
+export async function parseSpec(source) {
+    let api;
+    if (typeof source === "string") {
+        // Parse raw YAML/JSON first (no ref resolution)
+        const raw = await SwaggerParser.parse(source);
+        stripRootExtensions(raw);
+        ensurePathsKey(raw);
+        api = await SwaggerParser.dereference(raw);
+    }
+    else if (isOpenApiDocument(source)) {
+        const copy = structuredClone(source);
+        stripRootExtensions(copy);
+        ensurePathsKey(copy);
+        api = await SwaggerParser.dereference(copy);
+    }
+    else {
+        throw new Error("Invalid OpenAPI spec: must be a string path or an OpenAPI document object");
+    }
+    const isSwagger2 = "swagger" in api && typeof api.swagger === "string";
+    const title = api.info?.title ?? "Untitled";
+    const version = api.info?.version ?? "0.0.0";
+    let basePath = "";
+    if (isSwagger2 && "basePath" in api) {
+        const bp = api.basePath;
+        basePath = typeof bp === "string" ? bp : "";
+    }
+    else if ("servers" in api &&
+        Array.isArray(api.servers) &&
+        api.servers.length > 0) {
+        const firstServer = api.servers[0];
+        if (isRecord(firstServer) && typeof firstServer.url === "string") {
+            try {
+                const url = new URL(firstServer.url, "http://localhost");
+                basePath = url.pathname === "/" ? "" : url.pathname;
+            }
+            catch {
+                basePath = "";
+            }
+        }
+    }
+    // Strip trailing slash from basePath
+    if (basePath.endsWith("/") && basePath !== "/") {
+        basePath = basePath.slice(0, -1);
+    }
+    const paths = [];
+    const rawPaths = "paths" in api && isRecord(api.paths) ? api.paths : undefined;
+    if (!rawPaths) {
+        return { title, version, basePath, paths };
+    }
+    for (const [pathTemplate, pathItemRaw] of Object.entries(rawPaths)) {
+        if (!isRecord(pathItemRaw))
+            continue;
+        const pathItem = pathItemRaw;
+        // Extract path-level parameters
+        const pathLevelParams = extractParameters(Array.isArray(pathItem.parameters) ? pathItem.parameters : undefined, isSwagger2);
+        for (const methodKey of Object.keys(pathItem)) {
+            if (!HTTP_METHOD_KEYS.has(methodKey))
+                continue;
+            const operation = pathItem[methodKey];
+            if (!isRecord(operation))
+                continue;
+            const method = toHttpMethod(methodKey.toUpperCase());
+            // Merge path-level + operation-level parameters (operation wins)
+            const operationParams = extractParameters(Array.isArray(operation.parameters) ? operation.parameters : undefined, isSwagger2);
+            const mergedParams = mergeParameters(pathLevelParams, operationParams);
+            // Extract request body
+            let requestBody;
+            if (isSwagger2) {
+                requestBody = extractSwagger2RequestBody(mergedParams);
+            }
+            else {
+                requestBody = extractOpenApi3RequestBody(isRecord(operation.requestBody) ? operation.requestBody : undefined);
+            }
+            // Extract responses
+            const responses = extractResponses(isRecord(operation.responses) ? operation.responses : undefined, isSwagger2);
+            // Convert path template: {petId} -> :petId
+            const expressPath = convertPathTemplate(pathTemplate);
+            const tags = Array.isArray(operation.tags)
+                ? operation.tags.filter((t) => typeof t === "string")
+                : [];
+            // Filter out body parameters from the final parameter list (Swagger 2.0)
+            const filteredParams = mergedParams.filter(isNotBodyParam);
+            paths.push({
+                path: expressPath,
+                method,
+                operationId: getString(operation.operationId),
+                parameters: filteredParams,
+                requestBody,
+                responses,
+                tags,
+            });
+        }
+    }
+    return { title, version, basePath, paths };
+}
+function isValidParamLocation(location, isSwagger2) {
+    const validLocations = isSwagger2
+        ? ["path", "query", "header", "body"]
+        : ["path", "query", "header"];
+    return validLocations.includes(location);
+}
+function isNotBodyParam(param) {
+    return param.in !== "body";
+}
+function extractParameters(params, isSwagger2) {
+    if (!params || !Array.isArray(params))
+        return [];
+    return params
+        .filter((p) => isRecord(p))
+        .map((p) => {
+        const location = getString(p.in);
+        if (!location || !isValidParamLocation(location, isSwagger2)) {
+            return null;
+        }
+        let schema;
+        if (isSwagger2) {
+            // Swagger 2.0: schema is inline on the parameter (type, format, etc.)
+            if (location === "body") {
+                schema = isRecord(p.schema)
+                    ? normalizeSchema(p.schema, "request")
+                    : undefined;
+            }
+            else {
+                schema = p.type
+                    ? normalizeSchema({ type: p.type, format: p.format, enum: p.enum }, "request")
+                    : undefined;
+            }
+        }
+        else {
+            // OpenAPI 3.x: schema is nested
+            schema = isRecord(p.schema)
+                ? normalizeSchema(p.schema, "request")
+                : undefined;
+        }
+        const name = getString(p.name);
+        if (!name)
+            return null;
+        return {
+            name,
+            in: location,
+            required: getBoolean(p.required, false),
+            schema,
+        };
+    })
+        .filter((p) => p !== null);
+}
+function mergeParameters(pathLevel, operationLevel) {
+    const merged = new Map();
+    // Path-level first
+    for (const p of pathLevel) {
+        merged.set(`${p.in}:${p.name}`, p);
+    }
+    // Operation-level overwrites
+    for (const p of operationLevel) {
+        merged.set(`${p.in}:${p.name}`, p);
+    }
+    return [...merged.values()];
+}
+function extractSwagger2RequestBody(params) {
+    const bodyParam = params.find((p) => p.in === "body");
+    return bodyParam?.schema;
+}
+function extractOpenApi3RequestBody(requestBody) {
+    if (!requestBody)
+        return undefined;
+    const content = isRecord(requestBody.content)
+        ? requestBody.content
+        : undefined;
+    if (!content)
+        return undefined;
+    const jsonEntry = findJsonContent(content);
+    if (!jsonEntry)
+        return undefined;
+    const schema = isRecord(jsonEntry.schema) ? jsonEntry.schema : undefined;
+    if (!schema)
+        return undefined;
+    return normalizeSchema(schema, "request");
+}
+function extractResponses(responses, isSwagger2) {
+    const result = new Map();
+    if (!responses)
+        return result;
+    for (const [statusCode, response] of Object.entries(responses)) {
+        if (statusCode === "default")
+            continue;
+        if (!isRecord(response))
+            continue;
+        const code = Number.parseInt(statusCode, 10);
+        if (Number.isNaN(code))
+            continue;
+        const description = getString(response.description) ?? "";
+        let schema;
+        if (isSwagger2) {
+            // Swagger 2.0: schema is directly on the response
+            if (isRecord(response.schema)) {
+                schema = normalizeSchema(response.schema, "response");
+            }
+        }
+        else {
+            // OpenAPI 3.x: schema is nested in content
+            const content = isRecord(response.content) ? response.content : undefined;
+            if (content) {
+                const jsonEntry = findJsonContent(content);
+                if (jsonEntry && isRecord(jsonEntry.schema)) {
+                    schema = normalizeSchema(jsonEntry.schema, "response");
+                }
+            }
+        }
+        result.set(code, { schema, description });
+    }
+    return result;
+}
+/**
+ * Find the best JSON-like content type entry from an OpenAPI content map.
+ * Prefers application/json, then any *+json or *json* type.
+ */
+function findJsonContent(content) {
+    // Prefer exact application/json
+    if (isRecord(content["application/json"])) {
+        return content["application/json"];
+    }
+    // Try any JSON-like content type (application/problem+json, etc.)
+    for (const [type, value] of Object.entries(content)) {
+        if (type.includes("json") && isRecord(value)) {
+            return value;
+        }
+    }
+    // Fallback to first content type
+    return Object.values(content).find((v) => isRecord(v));
+}
+function convertPathTemplate(path) {
+    return path.replace(/\{([^}]+)\}/g, ":$1");
+}

package/dist/plugin.d.ts

@@ -0,0 +1,32 @@
+import type { SeedConfig, SeedSource } from "./seed.js";
+export type { SeedConfig, SeedSource };
+export interface OpenApiOptions {
+    /** File path or inline spec object */
+    spec: string | object;
+    /** Optional seed data per resource */
+    seed?: SeedConfig;
+    /** Validate request bodies (default: true) */
+    validateRequests?: boolean;
+    /** Validate response bodies (default: false) */
+    validateResponses?: boolean;
+    /** Query features for list endpoints */
+    queryFeatures?: {
+        pagination?: boolean;
+        sorting?: boolean;
+        filtering?: boolean;
+    };
+}
+/**
+ * Create an OpenAPI plugin that auto-registers CRUD routes from a spec.
+ *
+ * @example
+ * ```typescript
+ * const mock = schmock();
+ * mock.pipe(await openapi({
+ *   spec: "./petstore.yaml",
+ *   seed: { pets: { count: 10 } },
+ * }));
+ * ```
+ */
+export declare function openapi(options: OpenApiOptions): Promise<Schmock.Plugin>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGxD,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;AAMvC,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,sCAAsC;IACtC,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,gDAAgD;IAChD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,wCAAwC;IACxC,aAAa,CAAC,EAAE;QACd,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAwCzB"}