Baklava: generate OpenAPI docs and TypeScript clients from your Pekko HTTP routing tests

[kkozlowska1]

We just open sourced baklava, a library that generates OpenAPI specs, HTML docs, and type-safe TypeScript clients directly from your Pekko HTTP (and http4s) routing tests.

The idea: instead of maintaining an OpenAPI file separately from your routes, you write test scenarios that both verify the endpoint's behavior and describe it for documentation output. When sbt test runs, baklava captures the actual request/response pairs and generates seven output formats from them: OpenAPI with Swagger UI, TS-REST, oRPC, a plain TypeScript fetch client, Postman, an sttp client, and browsable HTML. If a test passes, the docs it produces are accurate, because the same execution verified the behavior. If a route changes and the test breaks, the docs don't regenerate until it's fixed.

No migration of existing routes needed, it mixes into your existing ScalaTest/Specs2/MUnit suite alongside whatever you're already running.

Repo: https://github.com/theiterators/baklava

Posting here because Pekko HTTP is one of the two frameworks it supports, and wanted to see if this is useful to anyone else running into the same documentation drift problem.