@schmock/openapi 1.1.0

package/src/plugin.test.ts

@@ -0,0 +1,205 @@
+import { resolve } from "node:path";
+import { schmock } from "@schmock/core";
+import { describe, expect, it } from "vitest";
+import { openapi } from "./plugin";
+
+const fixturesDir = resolve(import.meta.dirname, "__fixtures__");
+
+describe("openapi plugin", () => {
+  describe("Swagger 2.0 integration", () => {
+    it("auto-registers all routes from Petstore spec", async () => {
+      const mock = schmock({ state: {} });
+      mock.pipe(
+        await openapi({ spec: `${fixturesDir}/petstore-swagger2.json` }),
+      );
+
+      // List (should be empty initially)
+      const listResponse = await mock.handle("GET", "/pets");
+      expect(listResponse.status).toBe(200);
+      expect(listResponse.body).toEqual([]);
+    });
+
+    it("CRUD lifecycle with Swagger 2.0", async () => {
+      const mock = schmock({ state: {} });
+      mock.pipe(
+        await openapi({ spec: `${fixturesDir}/petstore-swagger2.json` }),
+      );
+
+      // Create
+      const created = await mock.handle("POST", "/pets", {
+        body: { name: "Buddy", tag: "dog" },
+      });
+      expect(created.status).toBe(201);
+      expect(created.body).toMatchObject({ name: "Buddy", petId: 1 });
+
+      // Read
+      const read = await mock.handle("GET", "/pets/1");
+      expect(read.status).toBe(200);
+      expect(read.body).toMatchObject({ name: "Buddy", petId: 1 });
+
+      // Update
+      const updated = await mock.handle("PUT", "/pets/1", {
+        body: { name: "Max" },
+      });
+      expect(updated.status).toBe(200);
+      expect(updated.body).toMatchObject({ name: "Max", petId: 1 });
+
+      // List
+      const list = await mock.handle("GET", "/pets");
+      expect(list.status).toBe(200);
+      expect(list.body).toHaveLength(1);
+
+      // Delete
+      const deleted = await mock.handle("DELETE", "/pets/1");
+      expect(deleted.status).toBe(204);
+
+      // Verify deletion
+      const afterDelete = await mock.handle("GET", "/pets/1");
+      expect(afterDelete.status).toBe(404);
+      expect(afterDelete.body).toMatchObject({
+        error: "Not found",
+        code: "NOT_FOUND",
+      });
+    });
+
+    it("handles non-CRUD endpoints", async () => {
+      const mock = schmock({ state: {} });
+      mock.pipe(
+        await openapi({ spec: `${fixturesDir}/petstore-swagger2.json` }),
+      );
+
+      // Health endpoint — should return a generated response
+      const health = await mock.handle("GET", "/health");
+      expect(health.status).toBe(200);
+      expect(health.body).toBeDefined();
+    });
+  });
+
+  describe("OpenAPI 3.0 integration", () => {
+    it("auto-registers routes from OpenAPI 3.0 spec", async () => {
+      const mock = schmock({ state: {} });
+      mock.pipe(
+        await openapi({ spec: `${fixturesDir}/petstore-openapi3.json` }),
+      );
+
+      const list = await mock.handle("GET", "/pets");
+      expect(list.status).toBe(200);
+      expect(Array.isArray(list.body)).toBe(true);
+    });
+  });
+
+  describe("seed data", () => {
+    it("seeds inline data", async () => {
+      const mock = schmock({ state: {} });
+      mock.pipe(
+        await openapi({
+          spec: `${fixturesDir}/petstore-swagger2.json`,
+          seed: {
+            pets: [
+              { petId: 1, name: "Buddy" },
+              { petId: 2, name: "Max" },
+            ],
+          },
+        }),
+      );
+
+      const list = await mock.handle("GET", "/pets");
+      expect(list.status).toBe(200);
+      expect(list.body).toHaveLength(2);
+    });
+
+    it("seeds auto-generated data from schema", async () => {
+      const mock = schmock({ state: {} });
+      mock.pipe(
+        await openapi({
+          spec: `${fixturesDir}/petstore-swagger2.json`,
+          seed: {
+            pets: { count: 5 },
+          },
+        }),
+      );
+
+      const list = await mock.handle("GET", "/pets");
+      expect(list.status).toBe(200);
+      expect(list.body).toHaveLength(5);
+    });
+
+    it("seeded data works with read endpoints", async () => {
+      const mock = schmock({ state: {} });
+      mock.pipe(
+        await openapi({
+          spec: `${fixturesDir}/petstore-swagger2.json`,
+          seed: {
+            pets: [{ petId: 42, name: "Luna" }],
+          },
+        }),
+      );
+
+      const read = await mock.handle("GET", "/pets/42");
+      expect(read.status).toBe(200);
+      expect(read.body).toMatchObject({ petId: 42, name: "Luna" });
+    });
+
+    it("continues auto-incrementing after seeded data", async () => {
+      const mock = schmock({ state: {} });
+      mock.pipe(
+        await openapi({
+          spec: `${fixturesDir}/petstore-swagger2.json`,
+          seed: {
+            pets: [
+              { petId: 1, name: "Buddy" },
+              { petId: 2, name: "Max" },
+            ],
+          },
+        }),
+      );
+
+      const created = await mock.handle("POST", "/pets", {
+        body: { name: "New" },
+      });
+      expect(created.status).toBe(201);
+      // Should get ID 3 since max existing ID is 2
+      expect(created.body).toMatchObject({ petId: 3 });
+    });
+  });
+
+  describe("404 handling", () => {
+    it("returns 404 for non-existent items", async () => {
+      const mock = schmock({ state: {} });
+      mock.pipe(
+        await openapi({ spec: `${fixturesDir}/petstore-swagger2.json` }),
+      );
+
+      const read = await mock.handle("GET", "/pets/999");
+      expect(read.status).toBe(404);
+      expect(read.body).toMatchObject({
+        error: "Not found",
+        code: "NOT_FOUND",
+      });
+    });
+  });
+
+  describe("state isolation", () => {
+    it("isolates state between separate mock instances", async () => {
+      const mock1 = schmock({ state: {} });
+      mock1.pipe(
+        await openapi({ spec: `${fixturesDir}/petstore-swagger2.json` }),
+      );
+
+      const mock2 = schmock({ state: {} });
+      mock2.pipe(
+        await openapi({ spec: `${fixturesDir}/petstore-swagger2.json` }),
+      );
+
+      await mock1.handle("POST", "/pets", { body: { name: "A" } });
+
+      const list1 = await mock1.handle("GET", "/pets");
+      const list2 = await mock2.handle("GET", "/pets");
+
+      const body1 = list1.body;
+      const body2 = list2.body;
+      expect(Array.isArray(body1) && body1.length).toBe(1);
+      expect(Array.isArray(body2) && body2.length).toBe(0);
+    });
+  });
+});

package/src/plugin.ts

@@ -0,0 +1,185 @@
+/// <reference path="../../../types/schmock.d.ts" />
+
+import type { CrudResource } from "./crud-detector.js";
+import { detectCrudResources } from "./crud-detector.js";
+import {
+  createCreateGenerator,
+  createDeleteGenerator,
+  createListGenerator,
+  createReadGenerator,
+  createStaticGenerator,
+  createUpdateGenerator,
+} from "./generators.js";
+import { parseSpec } from "./parser.js";
+import type { SeedConfig, SeedSource } from "./seed.js";
+import { loadSeed } from "./seed.js";
+
+export type { SeedConfig, SeedSource };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+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 async function openapi(
+  options: OpenApiOptions,
+): Promise<Schmock.Plugin> {
+  const spec = await parseSpec(options.spec);
+  const { resources, nonCrudPaths } = detectCrudResources(spec.paths);
+  const seedData = options.seed
+    ? loadSeed(options.seed, resources)
+    : new Map<string, unknown[]>();
+
+  return {
+    name: "@schmock/openapi",
+    version: "1.0.0",
+
+    install(instance: Schmock.CallableMockInstance) {
+      // Seed initial state — we need state to be initialized before registering routes
+      // The state is populated via generator context.state on first request,
+      // but we need to pre-populate it. We'll use a global config state approach.
+      // Since generators use ctx.state (the global config state), we set up seed
+      // data through a setup route that runs on first access, or we just seed
+      // in the generators themselves.
+
+      // Register CRUD routes
+      for (const resource of resources) {
+        registerCrudRoutes(instance, resource, seedData.get(resource.name));
+      }
+
+      // Register non-CRUD routes with static generators
+      for (const parsedPath of nonCrudPaths) {
+        const routeKey =
+          `${parsedPath.method} ${parsedPath.path}` as Schmock.RouteKey;
+        instance(routeKey, createStaticGenerator(parsedPath));
+      }
+    },
+
+    process(
+      context: Schmock.PluginContext,
+      response?: unknown,
+    ): Schmock.PluginResult {
+      // Pass through — generators handle everything
+      return { context, response };
+    },
+  };
+}
+
+function registerCrudRoutes(
+  instance: Schmock.CallableMockInstance,
+  resource: CrudResource,
+  seedItems?: unknown[],
+): void {
+  // Create a seeded generator wrapper that initializes state on first call
+  const ensureSeeded = createSeeder(resource, seedItems);
+
+  for (const op of resource.operations) {
+    switch (op) {
+      case "list": {
+        const gen = createListGenerator(resource);
+        const routeKey = `GET ${resource.basePath}` as Schmock.RouteKey;
+        instance(routeKey, wrapWithSeeder(ensureSeeded, gen));
+        break;
+      }
+      case "create": {
+        const gen = createCreateGenerator(resource);
+        const routeKey = `POST ${resource.basePath}` as Schmock.RouteKey;
+        instance(routeKey, wrapWithSeeder(ensureSeeded, gen));
+        break;
+      }
+      case "read": {
+        const gen = createReadGenerator(resource);
+        const routeKey = `GET ${resource.itemPath}` as Schmock.RouteKey;
+        instance(routeKey, wrapWithSeeder(ensureSeeded, gen));
+        break;
+      }
+      case "update": {
+        const gen = createUpdateGenerator(resource);
+        const putKey = `PUT ${resource.itemPath}` as Schmock.RouteKey;
+        const patchKey = `PATCH ${resource.itemPath}` as Schmock.RouteKey;
+        instance(putKey, wrapWithSeeder(ensureSeeded, gen));
+        instance(patchKey, wrapWithSeeder(ensureSeeded, gen));
+        break;
+      }
+      case "delete": {
+        const gen = createDeleteGenerator(resource);
+        const routeKey = `DELETE ${resource.itemPath}` as Schmock.RouteKey;
+        instance(routeKey, wrapWithSeeder(ensureSeeded, gen));
+        break;
+      }
+    }
+  }
+}
+
+/**
+ * Create a seeder function that initializes collection state once.
+ */
+function createSeeder(
+  resource: CrudResource,
+  seedItems?: unknown[],
+): (state: Record<string, unknown>) => void {
+  const stateKey = `openapi:collections:${resource.name}`;
+  const counterKey = `openapi:counter:${resource.name}`;
+  const seededKey = `openapi:seeded:${resource.name}`;
+
+  return (state: Record<string, unknown>) => {
+    if (state[seededKey]) return;
+    state[seededKey] = true;
+
+    if (seedItems && seedItems.length > 0) {
+      state[stateKey] = [...seedItems];
+      // Set counter to highest existing ID
+      let maxId = 0;
+      for (const item of seedItems) {
+        if (isRecord(item) && resource.idParam in item) {
+          const id = item[resource.idParam];
+          if (typeof id === "number" && id > maxId) {
+            maxId = id;
+          }
+        }
+      }
+      state[counterKey] = maxId;
+    } else {
+      state[stateKey] = [];
+      state[counterKey] = 0;
+    }
+  };
+}
+
+function wrapWithSeeder(
+  seeder: (state: Record<string, unknown>) => void,
+  generator: Schmock.GeneratorFunction,
+): Schmock.GeneratorFunction {
+  return (ctx: Schmock.RequestContext) => {
+    seeder(ctx.state);
+    return generator(ctx);
+  };
+}

package/src/seed.ts

@@ -0,0 +1,62 @@
+/// <reference path="../../../types/schmock.d.ts" />
+
+import { readFileSync } from "node:fs";
+import type { CrudResource } from "./crud-detector.js";
+import { generateSeedItems } from "./generators.js";
+
+export type SeedSource = unknown[] | string | { count: number };
+
+export type SeedConfig = Record<string, SeedSource>;
+
+/**
+ * Load seed data for CRUD resources.
+ *
+ * Sources:
+ * - unknown[]: inline array of objects
+ * - string: file path to a JSON array
+ * - { count: number }: auto-generate N items from resource schema
+ */
+export function loadSeed(
+  config: SeedConfig,
+  resources: CrudResource[],
+): Map<string, unknown[]> {
+  const result = new Map<string, unknown[]>();
+
+  for (const [resourceName, source] of Object.entries(config)) {
+    const resource = resources.find((r) => r.name === resourceName);
+
+    if (Array.isArray(source)) {
+      // Inline array
+      result.set(resourceName, [...source]);
+    } else if (typeof source === "string") {
+      // File path
+      const content = readFileSync(source, "utf-8");
+      const parsed: unknown = JSON.parse(content);
+      if (!Array.isArray(parsed)) {
+        throw new Error(
+          `Seed file "${source}" for resource "${resourceName}" must contain a JSON array`,
+        );
+      }
+      result.set(resourceName, parsed);
+    } else if (
+      typeof source === "object" &&
+      source !== null &&
+      "count" in source
+    ) {
+      // Auto-generate from schema
+      if (!resource?.schema) {
+        throw new Error(
+          `Cannot auto-generate seed for "${resourceName}": no schema found in spec`,
+        );
+      }
+      const items = generateSeedItems(
+        resource.schema,
+        source.count,
+        resource.idParam,
+      );
+      result.set(resourceName, items);
+    }
+  }
+
+  return result;
+}

package/src/steps/openapi-crud.steps.ts

@@ -0,0 +1,132 @@
+import { resolve } from "node:path";
+import { describeFeature, loadFeature } from "@amiceli/vitest-cucumber";
+import { schmock } from "@schmock/core";
+import { expect } from "vitest";
+import { openapi } from "../plugin";
+
+const feature = await loadFeature("../../features/openapi-crud.feature");
+const fixturesDir = resolve(import.meta.dirname, "../__fixtures__");
+
+describeFeature(feature, ({ Scenario }) => {
+  let mock: Schmock.CallableMockInstance;
+  let response: Schmock.Response;
+  let createdId: number;
+
+  Scenario("Full CRUD lifecycle", ({ Given, When, Then, And }) => {
+    Given("a mock with the Petstore spec loaded", async () => {
+      mock = schmock({ state: {} });
+      mock.pipe(
+        await openapi({ spec: `${fixturesDir}/petstore-swagger2.json` }),
+      );
+    });
+
+    When("I create a pet named {string}", async (_, name: string) => {
+      response = await mock.handle("POST", "/pets", {
+        body: { name, tag: "dog" },
+      });
+      const body = response.body as Record<string, unknown>;
+      createdId = body.petId as number;
+    });
+
+    Then("the create response has status 201", () => {
+      expect(response.status).toBe(201);
+    });
+
+    And("the created pet has name {string}", (_, name: string) => {
+      const body = response.body as Record<string, unknown>;
+      expect(body.name).toBe(name);
+    });
+
+    When("I read the created pet", async () => {
+      response = await mock.handle("GET", `/pets/${createdId}`);
+    });
+
+    Then("the read response has status 200", () => {
+      expect(response.status).toBe(200);
+    });
+
+    And("the pet has name {string}", (_, name: string) => {
+      const body = response.body as Record<string, unknown>;
+      expect(body.name).toBe(name);
+    });
+
+    When("I update the pet name to {string}", async (_, name: string) => {
+      response = await mock.handle("PUT", `/pets/${createdId}`, {
+        body: { name },
+      });
+    });
+
+    Then("the update response has status 200", () => {
+      expect(response.status).toBe(200);
+    });
+
+    When("I list all pets", async () => {
+      response = await mock.handle("GET", "/pets");
+    });
+
+    Then("the list contains {int} item", (_, count: number) => {
+      expect(response.body).toHaveLength(count);
+    });
+
+    When("I delete the pet", async () => {
+      response = await mock.handle("DELETE", `/pets/${createdId}`);
+    });
+
+    Then("the delete response has status 204", () => {
+      expect(response.status).toBe(204);
+    });
+
+    When("I list all pets after deletion", async () => {
+      response = await mock.handle("GET", "/pets");
+    });
+
+    Then("the list is empty", () => {
+      expect(response.body).toEqual([]);
+    });
+  });
+
+  Scenario(
+    "Read non-existent resource returns 404",
+    ({ Given, When, Then, And }) => {
+      Given("a mock with the Petstore spec loaded", async () => {
+        mock = schmock({ state: {} });
+        mock.pipe(
+          await openapi({ spec: `${fixturesDir}/petstore-swagger2.json` }),
+        );
+      });
+
+      When("I read pet with id 999", async () => {
+        response = await mock.handle("GET", "/pets/999");
+      });
+
+      Then("the response status is 404", () => {
+        expect(response.status).toBe(404);
+      });
+
+      And("the response has error code {string}", (_, code: string) => {
+        const body = response.body as Record<string, unknown>;
+        expect(body.code).toBe(code);
+      });
+    },
+  );
+
+  Scenario(
+    "Delete non-existent resource returns 404",
+    ({ Given, When, Then }) => {
+      Given("a mock with the Petstore spec loaded", async () => {
+        mock = schmock({ state: {} });
+        mock.pipe(
+          await openapi({ spec: `${fixturesDir}/petstore-swagger2.json` }),
+        );
+      });
+
+      When("I delete pet with id 999", async () => {
+        response = await mock.handle("DELETE", "/pets/999");
+      });
+
+      Then("the response status is 404", () => {
+        expect(response.status).toBe(404);
+      });
+    },
+  );
+});

package/src/steps/openapi-parsing.steps.ts

@@ -0,0 +1,111 @@
+import { resolve } from "node:path";
+import { describeFeature, loadFeature } from "@amiceli/vitest-cucumber";
+import { schmock } from "@schmock/core";
+import { expect } from "vitest";
+import type { ParsedSpec } from "../parser";
+import { parseSpec } from "../parser";
+import { openapi } from "../plugin";
+
+const feature = await loadFeature("../../features/openapi-parsing.feature");
+const fixturesDir = resolve(import.meta.dirname, "../__fixtures__");
+
+describeFeature(feature, ({ Scenario }) => {
+  let parsedSpec: ParsedSpec;
+  let mock: Schmock.CallableMockInstance;
+
+  Scenario("Parse Swagger 2.0 spec", ({ Given, When, Then, And }) => {
+    Given("a Swagger 2.0 Petstore spec", () => {
+      // Spec will be loaded in the When step
+    });
+
+    When("I create an openapi plugin from the spec", async () => {
+      parsedSpec = await parseSpec(`${fixturesDir}/petstore-swagger2.json`);
+    });
+
+    Then("the parsed spec has title {string}", (_, title: string) => {
+      expect(parsedSpec.title).toBe(title);
+    });
+
+    And("the parsed spec has version {string}", (_, version: string) => {
+      expect(parsedSpec.version).toBe(version);
+    });
+
+    And("the parsed spec has basePath {string}", (_, basePath: string) => {
+      expect(parsedSpec.basePath).toBe(basePath);
+    });
+  });
+
+  Scenario("Parse OpenAPI 3.0 spec", ({ Given, When, Then, And }) => {
+    Given("an OpenAPI 3.0 Petstore spec", () => {
+      // Spec will be loaded in the When step
+    });
+
+    When("I create an openapi plugin from the spec", async () => {
+      parsedSpec = await parseSpec(`${fixturesDir}/petstore-openapi3.json`);
+      mock = schmock({ state: {} });
+      mock.pipe(
+        await openapi({ spec: `${fixturesDir}/petstore-openapi3.json` }),
+      );
+    });
+
+    Then("the parsed spec has title {string}", (_, title: string) => {
+      expect(parsedSpec.title).toBe(title);
+    });
+
+    And("the parsed spec has version {string}", (_, version: string) => {
+      expect(parsedSpec.version).toBe(version);
+    });
+
+    And("routes are auto-registered from the spec", async () => {
+      const response = await mock.handle("GET", "/pets");
+      expect(response.status).toBe(200);
+    });
+  });
+
+  Scenario("Parse inline spec object", ({ Given, When, Then }) => {
+    Given("an inline OpenAPI spec object", () => {
+      // Inline spec prepared in When step
+    });
+
+    When("I create an openapi plugin from the inline spec", async () => {
+      mock = schmock({ state: {} });
+      mock.pipe(
+        await openapi({
+          spec: {
+            openapi: "3.0.3",
+            info: { title: "Inline", version: "1.0.0" },
+            paths: {
+              "/hello": {
+                get: {
+                  responses: {
+                    "200": {
+                      description: "Hello",
+                      content: {
+                        "application/json": {
+                          schema: {
+                            type: "object",
+                            properties: { msg: { type: "string" } },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+                post: {
+                  responses: {
+                    "201": { description: "Created" },
+                  },
+                },
+              },
+            },
+          },
+        }),
+      );
+    });
+
+    Then("routes are registered from the inline spec", async () => {
+      const response = await mock.handle("GET", "/hello");
+      expect(response.status).toBe(200);
+    });
+  });
+});