Baklava turns Scala API tests into living documentation
API documentation always lags behind the code—until now. Baklava, an open-source Scala library, flips the script by treating routing tests as the single source of truth for both behaviour and documentation. When tests pass, the library emits human-readable HTML, a machine-readable OpenAPI spec, and ready-to-use TypeScript clients. Documentation drift becomes structurally impossible because the docs are generated only when the tests pass.
Tests that double as documentation
Baklava integrates directly into existing test suites for Pekko HTTP and http4s. Instead of writing assertions, developers define routes with path(), supports(), and onRequest() blocks that both verify API behaviour and describe it for documentation output. A failing test blocks documentation generation, ensuring the published contract always matches the running service. The approach eliminates the manual overhead of keeping specs in sync.
Seven formats, one pipeline
Each supported output—Simple HTML, OpenAPI 3.0.1, TypeScript packages, Postman collections, and Scala sttp clients—is generated automatically via SBT. The library supports Scala 2.13 and 3, JDK 11+, and integrates with ScalaTest, Specs2, and MUnit. Because every format is an independent SBT dependency discovered at runtime, teams can adopt only what they need without rewriting tooling.
A cultural shift for API teams
Why it matters
Baklava addresses the root cause of unreliable API documentation—parallel maintenance—by making the test suite the authoritative contract. Teams that adopt it cut the risk of production failures from stale specs and reduce the cognitive load of keeping multiple artifacts in sync. In environments where API contracts drive downstream development, this library transforms documentation from a liability into a by-product of good engineering.
Source: DEV Community. AI-assisted editorial synthesis — TechnoExpress.