Stoplight

Promptfree, for everyone, and the only version there is

Copy the prompt for Claude CodeCopy the prompt for CodexCopy the prompt for Cursor

Copy

Build me the API design and documentation workflow that replaces Stoplight.

Everything here exists as excellent free tools already. **The build is wiring them together in your pipeline**, and that is a genuinely small job with a large payoff.

STACK
- OpenAPI 3.1 in git, one file per API, split into components
- Spectral for style rules
- Prism for the mock server
- Redocly or Scalar for the published reference
- Node 20+ with Fastify for the small hosted parts
- Caddy in front

THE PIPELINE, WHICH IS THE WHOLE PRODUCT
- The description lives in git beside the code. **A description edited in a web tool and exported by hand drifts from the implementation within a month** — that is the failure this replaces
- On every pull request: validate the description, run the style rules, and fail the build on an error
- On merge: build the reference documentation and publish it as static files, and start a mock server from the same file

STYLE RULES WORTH ENFORCING
- Every operation has an operationId, a summary and at least one example
- Every response documents its error shapes, not only the happy path
- Naming consistent: plural collections, kebab or snake chosen once, and enforced
- **Breaking change detection between the merged description and the previous one**, failing the build unless the version is bumped. This is the single most valuable rule and almost nobody has it

THE MOCK, WHICH IS UNDERUSED
- Prism serves the description as a working API with example responses
- A frontend team builds against it before the backend exists, and an integration partner tests against it before you deploy
- Validation mode on: a request that violates the description fails against the mock, which catches the mismatch early

THE DOCUMENTATION
- Generated from the description on every merge, published statically. Nothing to run and nothing to keep in step
- A try-it panel pointing at a sandbox, never at production
- Search built at build time with Pagefind

KEEPING DESCRIPTION AND CODE TOGETHER
- Contract tests in the API's own test suite, asserting real responses against the description. **A description that is not tested is a document, not a contract**
- Or generate the description from the code and check the diff in the pull request. Either direction works; drifting in neither is the requirement

WHAT MATTERS MOST
Breaking change detection and contract tests. Editors and portals are commodity; those two are what make the description trustworthy.