Every time I had to test an API endpoint while writing an OpenAPI spec, I had to leave VS Code, open Postman, configure the request, and then come back. And if I wanted to check whether my changes broke any contracts — that meant running a separate diff tool.
I got tired of it. So I built Specter Mock.
What It Does
Specter Mock is a VS Code extension with three core features:
1. Local Mock Server
Open any OpenAPI .yaml or .json file, click the status bar — a local HTTP server starts on localhost:4010 instantly. No Docker, no CLI, no configuration.
curl localhost:4010/pets
# → [{"id": 1, "name": "Rex"}, {"id": 2, "name": "Whiskers"}]
It reads the examples from your spec and serves them as real HTTP responses.
2. Try It Panel
A built-in panel that lists all your endpoints with colored method badges. Click any endpoint, hit Send — you get the response right inside VS Code. GET, POST, PUT, DELETE — all work out of the box.
3. Breaking Change Diff
Every time you save your spec, Specter compares it against the last Git commit and shows breaking changes in the VS Code Problems panel:
Removed endpoints → Error
Removed parameters → Error
New required parameters → Warning
Changed response types → Error
No manual diffing. No extra commands. Just save and see.
Why I Built It
The existing tools each solve one piece of the puzzle:
- Postman — great API client, but it's a separate app
- Prism — powerful mock server, but CLI-only
- 42Crunch — good editor, but no local mock server
- oasdiff — excellent diff tool, but you have to run it manually
Nobody combined all three into a single VS Code extension. So I did.
How It Works Under the Hood
The mock server uses Node's built-in http module + @apidevtools/swagger-parser to dereference the spec and serve examples. No Prism dependency (I tried — it has ESM/CJS compatibility hell with newer faker versions).
The diff runs simple-git to get the previous file version from HEAD, writes it to a temp file, parses both versions with swagger-parser, and compares paths, methods, parameters, and response schemas. Results go directly into vscode.DiagnosticCollection.
The Try It panel is a Webview with plain HTML — no React, no bundler. Fetch requests go through the extension host (Node.js) to avoid CORS issues inside the webview sandbox.
The Bundling Problem
The trickiest part was bundling. I used esbuild, which is fast and simple. But @stoplight/prism-http uses jsonc-parser with a dynamic require('./impl/format') in its UMD build — esbuild bundles everything into one file and breaks the relative path.
The fix: --packages=external flag. This tells esbuild not to bundle node_modules — they stay as-is and load via native Node.js require. Bundle size dropped from 10.9mb to 20kb.
"compile": "esbuild src/extension.ts --bundle --outfile=dist/extension.js --external:vscode --packages=external --platform=node --target=node18"
Install It
Search "Specter Mock" in VS Code Extensions, or:
code --install-extension li0lik.specter-mock
What's Next
- Stateful mock scenarios (remember POST'd data for GET)
- Schema-based response generation (not just examples)
- OpenAPI linting in the Problems panel
If you work with OpenAPI specs daily, give it a try and let me know what you think. Issues and PRs welcome.
Top comments (0)