I built a Go CLI that makes OpenAPI specs executable here's why

Seven months ago I posted about a side project on X and LinkedIn and got basically no response. One star on GitHub my own.

I shelved it. But I kept thinking about the problem it was trying to solve, because the problem kept showing up in my actual work.

So I'm picking it back up, and this time I want to actually explain why I think it matters.

The problem I kept running into

I work with APIs. Like most backend developers, I maintain an OpenAPI spec for documentation and something else a Postman collection, Bruno workspace, test scripts for actually validating that the API works.

These two things describe the same API. They always have to agree with each other. But keeping them in sync is manual, and manual sync always fails eventually. Someone updates the spec, forgets the tests. Someone updates the tests, forgets the spec. Six months later you have documentation that lies and tests that test things that no longer exist.

This bothered me enough that I built something.

What I built

VolcAPI a Go CLI that makes your OpenAPI spec the single source of truth for both documentation and testing.

The core idea: use an OpenAPI extension (v-functional-test) to attach test scenarios directly to endpoint definitions. Now when you update the spec, you update the tests. They're the same file.

paths:
 /products/{id}:
 get:
 summary: Get product
 v-functional-test:
 scenarios: ["get_existing", "get_missing"]

scenarios:
 get_existing:
 query:
 id: 123
 response:
 status: 200
 body:
 json:
 id:
 value: 123

 get_missing:
 query:
 id: 99999
 response:
 status: 404

Run it:

volcapi run volcapi_local.yml -o openapi.yml

Go binary. No runtime. Drop it in CI.

Why I chose Go

Partly because I like Go. Partly because a static binary with no runtime dependencies is genuinely better for a CLI tool that runs in CI. You add it to a GitHub Actions workflow by downloading the binary no npm install, no pip install, no setup step. For a tool that runs on every PR, that matters.

Where it is and where I'm taking it

This is alpha. GET/POST/PUT/DELETE work. Response validation works. Environment configs work so you can run the same tests against local, staging, and production.

What I'm building next:

• JUnit XML output so GitHub Actions can parse results and show pass/fail inline

• A real, copy-paste GitHub Actions example

• Better contract validation fail CI when the response no longer matches what the spec says it returns

Longer term I want to add gRPC support and performance testing. But the CI story comes first, because that's what makes this useful to a team rather than just a curious developer.

What I'm looking for

If you're a backend developer who's felt the double-maintenance pain maintaining a spec and a separate test collection for the same API , I'd love to know if this approach makes sense to you. Not whether the code is polished (it isn't yet), but whether the model is right.

The repo: https://github.com/aliamerj/volcapi

I'm building this in public. If you're interested in following the progress or want to contribute, watch the repo. Feedback and criticism both welcome.

Go. MIT. Open source. Early.