DEV Community

Cover image for Generating OpenAPI specs without writing a single line of YAML
Mikołaj Badyl
Mikołaj Badyl

Posted on

Generating OpenAPI specs without writing a single line of YAML

#ai #programming #productivity #api

If you've ever tried to write an OpenAPI spec by hand, you know how painful it is. Hundreds of lines of YAML, manual endpoint definitions, request/response schemas - and if your API changes, you have to update it all again.

I ran into this problem while building Octrafic. The tool requires an OpenAPI spec to understand your API structure - and not everyone has one. So I built a scanner that generates it automatically from your source code.

How it works

The scanner uses a pipeline called OOPS that works in four stages.

1. Framework detection

It starts by reading your root config files - go.mod, package.json, requirements.txt and so on. From that it figures out your language and web framework without touching the rest of your codebase.

2. Route discovery

Using heuristics specific to the detected framework, it finds exactly which files contain your routing logic and endpoint definitions. It skips everything irrelevant - node_modules, test directories, etc.

3. Parallel endpoint extraction

Instead of dumping your entire codebase into the LLM context, it isolates each routing file and queries the AI in parallel. This keeps token usage low and extraction fast. It pulls out methods, paths, summaries, and request/response payloads.

4. Spec generation

Everything gets aggregated and formatted into a valid OpenAPI 3.1 YAML file, ready to use.

Usage

One command:

octrafic scan -p ./my-backend-project -o api-spec.yaml
Enter fullscreen mode Exit fullscreen mode

Once the scan finishes, you can immediately start testing:

octrafic -u http://localhost:8080 -s api-spec.yaml
Enter fullscreen mode Exit fullscreen mode

CI/CD support

The scanner runs completely non-interactively, so you can wire it into your pipeline:

export OCTRAFIC_PROVIDER=claude
export OCTRAFIC_API_KEY=your_key_here
export OCTRAFIC_MODEL=claude-haiku-4.5
octrafic scan -p . -o spec.yaml
Enter fullscreen mode Exit fullscreen mode

Why I built this

Octrafic lets you test APIs using plain English instead of writing test scripts. But it requires an OpenAPI spec to understand your API structure - without one, it can't work.

The scanner removes that barrier. You point it at your project, get a spec, and go straight to testing - without writing a single line of YAML.

It's open-source, still early, feedback welcome.

Top comments (0)