DEV Community

Cover image for Stop maintaining two files that describe the same API
Ali Amer
Ali Amer

Posted on

Stop maintaining two files that describe the same API

#api #go #showdev #testing

Show of hands: how many of you have an OpenAPI spec and a separate test collection that slowly drifted apart?

I'll wait.

Yeah. I've been there too. For a long time. And I finally got annoyed enough to build something about it.

The problem in one sentence

Your OpenAPI spec and your API tests describe the same thing, so they should be the same file.

What I built

VolcAPI — a Go CLI that makes your OpenAPI spec executable. You define test scenarios directly inside the spec using a v-functional-test extension, then run them from the terminal.

# Inside your openapi.yml
paths:
  /users:
    post:
      summary: Create user
      v-functional-test:
        scenarios: ["create_valid_user", "duplicate_email"]

scenarios:
  create_valid_user:
    headers:
      Content-Type: application/json
    request:
      name: Alice
      email: alice@example.com
    response:
      status: 201
      body:
        contains: ["id", "email"]

  duplicate_email:
    request:
      name: Alice
      email: existing@example.com
    response:
      status: 409
Enter fullscreen mode Exit fullscreen mode

Then:

volcapi run volcapi_local.yml -o openapi.yml
Enter fullscreen mode Exit fullscreen mode

Done. Both your documentation and your tests updated in one place.

Environment configs

Point at different hosts without changing your spec:

# volcapi_local.yml
host: http://localhost:3000
env:
  API_TOKEN: dev_token_here

# volcapi_staging.yml  
host: https://staging.api.myapp.com
env:
  API_TOKEN: ${STAGING_TOKEN}
Enter fullscreen mode Exit fullscreen mode

Why Go?

Single static binary. No node_modules. No Python virtualenv. Downloads in seconds, runs in CI with zero setup. Same reason K6 took off for performance testing.

Where it's at

Early alpha. This is what works today:

  • ✅ OpenAPI 3.x parsing
  • ✅ GET / POST / PUT / DELETE
  • ✅ Response status + JSON body validation
  • ✅ Environment variable substitution
  • 🔨 JUnit XML output (for CI integration) — in progress
  • 🔨 GitHub Actions example — in progress ## The bigger picture

Dredd used to own this space (OpenAPI-native API testing). It's been mostly unmaintained for years. Most of what replaced it is JavaScript-heavy or requires a cloud service. There's a real gap for a fast, Go-native, CI-first OpenAPI test runner. That's what I'm building.

Repo: https://github.com/aliamerj/volcapi

If this solves a problem you've felt — even a star helps me know the direction is right. And if you have opinions about the "spec as test suite" model (for or against), drop them in the comments. I'm still thinking through the design.

Built in Go. MIT licensed. v0.1.0-alpha.

Top comments (0)