Spec → Playbook: Generate OpenAPI Stubs from Playables to Cut Dev Time in Half

Playable demos (clickable prototypes, sandbox UIs, small demo backends) encode the product's expected interactions — exact endpoints, request shapes, and realistic responses — but that information often lives only in the designer or PM’s head. Turning those interactions into machine‑readable contracts prevents guesswork and reduces rework when contractors implement APIs.

Spec‑first artifacts (OpenAPI, contract tests, and mock servers) become the single source of truth teams can run locally and validate against. They accelerate onboarding, shrink clarification cycles, and make acceptance criteria executable before any production code is written.

The pipeline has four repeatable stages: record interactions from the playable, normalize payloads into JSON Schema, synthesize an OpenAPI document (paths, parameters, components), and emit artifacts: a mock server, acceptance tests, and feature cards. Each artifact targets a different role — mocks for frontend devs and QA, acceptance tests for CI, and feature cards for PMs and contractors.

This is contract‑first engineering: consumers (the playable) describe expectations and generate the contract that providers implement. Use a contract runner in CI to fail builds when provider behavior diverges from the spec.

Start with two capture techniques: record the playable’s network traffic (HAR export) or instrument the demo to emit structured interaction events (recommended for offline reproducibility). Use a small Node/Python script to convert examples into JSON Schema (ajv / jsonschema libraries) and to deduplicate similar payloads into schema candidates.

Feed those schemas and path templates into an OpenAPI generator script that emits an OpenAPI 3.1 document. From that document you can spawn three immediate artifacts: (A) a mock server (Prism, SpecJet, or OpenAPI Generator + lightweight express server); (B) acceptance tests (Postman collections or contract tests generated with Postman or Pact-style tools); and (C) one-line feature cards that include endpoint, example request/response, and acceptance condition.

The pattern below is intentionally minimal — it’s meant to be copy/pasted and adapted. Inputs: playable HAR or event JSON. Outputs: openapi.yaml, mock-server/ (Prism), tests/postman_collection.json, feature_cards.md. Steps: parse interactions → group by path template → infer schemas → render OpenAPI template → run mock server generator.

Don’t invent complex inference: prefer conservative schemas that validate required fields seen in examples and use 'oneOf' for variations. Where the playable shows optional fields, mark them optional in the schema. Include realistic example responses so contractors can run the mock server and verify behavior immediately.

Deliver the OpenAPI file alongside the playable and the mock server URL. Ask contractors to run the mock and pass the acceptance tests (Postman or Pact) locally before opening pull requests. This short-circuits the common back-and-forth: if the mock behaves as the playable demonstrated and tests pass, the implementation only needs to match the contract.

Treat the generated feature cards as the canonical tickets: each card contains endpoint, payload examples, success and failure acceptance tests, and a short performance note (expected latency or size limits). Keep review lightweight by requiring a provider verification run against the contract in CI (tools like Pact, Dredd, or direct OpenAPI validation).