Skip to content

spike/feat: minimal low-ceremony JSON frontend for integrators without a spec #99

Description

@MaxMichel2

Part of #72

Depends on #73 (the pure-seam design constraint is what makes this cheap to add). Explicitly demand-gated — do not pick this up speculatively.

Summary

A second, deliberately tiny, low-ceremony JSON input format for integrators who don't have (and don't want to hand-author) an OpenAPI spec, feeding the exact same internal model (ApiSpec, Operation, MockResponse) that the OpenAPI parser produces. This issue should only be picked up if real 0.2.0 adoption feedback shows integrators without an existing spec are actually blocked or frustrated by needing to write OpenAPI for a handful of endpoints — it is tracked here so the option is deliberately visible, not because it's scheduled.

Why this is safe to leave open rather than decide now

This came out of a design discussion (see epic #72's linked review) about whether 0.2.0 should ship two input formats from day one. The conclusion was no — nobody is currently blocked, and every config-expressible feature (delay via #A, failure-rate via #B, sequences via #C) would otherwise need to be designed against two schemas from day one, regardless of whether they compile to the same objects. But the objection had a real point worth preserving: DevView's architecture already makes a second frontend cheap to add later, because #73 requires MockConfigRepository to be a pure RawBytes -> ApiSpec function with no OpenAPI-specific type leaking downstream. Adding a second implementation of that same function signature is additive, not a rearchitecture — so there's no cost to deciding against building it now, only to building it prematurely.

What this explicitly is not

Not the old mocks.json restored as-is — that format carried the environment axis (EnvironmentConfig, endpointOverrides, additionalEndpoints) and the probe-based response discovery, both of which this migration removes for good reasons unrelated to the format question (see #74, #76). Reviving that shape would reintroduce exactly the complexity this epic exists to remove.

What to build, if and when this is picked up

  • A fresh, deliberately minimal schema: just enough to describe a handful of operations without any formal API-spec ceremony — id/path/method/name per operation, inline example response bodies (no separate response-file tree required, though one could still be supported for larger inline bodies).
  • No groups-as-environments, no override/merge mechanism — if an integrator's needs grow past what this minimal format comfortably expresses, the answer is "write OpenAPI," not "extend this format to match OpenAPI's feature set." Keeping this format deliberately less capable than OpenAPI is what keeps it cheap to maintain.
  • The parser for this format produces the exact same ApiSpec/Operation/MockResponse objects the OpenAPI parser does — reuse MockConfigRepository's existing seam, don't build a parallel engine.
  • If #D's build-time codegen spike has landed and been adopted by the time this is picked up, this frontend should feed the same build-time pipeline rather than becoming a second on-device runtime parser — but that's an implementation detail to settle at pickup time, not now.

Acceptance criteria (to refine when actually scoped)

  • Before starting implementation: confirm the demand signal that justifies building this (cite specific integrator feedback, not a hypothetical).
  • The new format's parser produces ApiSpec/Operation/MockResponse — no new types leak into devview-networkmock or devview-networkmock-ktor.
  • The new format is deliberately incapable of things OpenAPI can express that it chooses not to support (documented explicitly, not accidentally missing).

Files likely touched

TBD — deferred until picked up.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions