guardrail: generating server code from an OpenAPI specification

What guardrail generates and for what

guardrail is a code generation tool, capable of reading from OpenAPI/Swagger specification files and generating both Scala and Java source code, targeting various libraries and frameworks.

The targets are listed precisely, and the list is the clearest statement of what the tool is for. For Scala there is `akka-http` and `http4s`, both backed by `circe`, as well as `dropwizard` backed by `jackson`. For Java there is `dropwizard` and `spring-mvc`, both backed by `jackson`.

That is a server-side tool, and the distinction matters. The output is a server implementation: routing, request decoding, and the model types that appear in your API. If your problem is that a client and a server have drifted apart, this is not the tool for it.

The backing libraries are named for a reason. `circe` is the Scala JSON library and `jackson` the Java one, so the choice of HTTP framework determines the JSON layer that the generated code will use. That coupling is the main thing to know when you pick a target, because the generated code will reference those types directly.

The project is MIT licensed, the primary language is Scala, the default branch is master, the homepage is guardrail.dev, and the last push was on 2026-07-18. The topic tags list the same surface from the other side, with akka-http, cats, codegen, dropwizard, http4s, jackson, java, openapi, scala and swagger.

The badge set is worth a glance for a sense of the project's shape. There is a CI build status, a codecov coverage badge, a Matrix chat badge and a Gitter badge, a Scala Steward badge for dependency updates, and a note in the contributors section that the project was open sourced, with thanks to those who contributed before that happened.

Four ways to run it

guardrail is not only a command line program, and the four integration routes are the thing to understand before choosing.

The first three are build tool plugins, each in its own repository under the guardrail-dev organisation. `guardrail-dev/sbt-guardrail` is published to Maven Central as `dev.guardrail:sbt-guardrail`, `guardrail-dev/guardrail-maven-plugin` as `dev.guardrail:guardrail-maven-plugin`, and `guardrail-dev/guardrail-gradle-plugin` as `dev.guardrail`, available from the Gradle Plugin Portal. Each has a documentation page in the repository's own docs directory, under `docs/plugins`.

The fourth is the CLI, which lives in the `modules/cli` directory of this repository rather than in a separate one, and is installed with `cs install guardrail`, the Coursier command for installing JVM applications. Its docs are at `docs/plugins/make.md`.

So a Scala team using sbt would add the plugin to their build and regenerate on demand, a Java team using Maven or Gradle would do the equivalent, and anyone who wants a one-shot run has the standalone command. The plugin route is the one that makes sense for a project where the specification changes alongside the code, because generation becomes a build step rather than something you remember to run.

The documentation site is at guardrail.dev, and the README directs newcomers there with a short line: New to guardrail? Check out the docs.

There is a companion document that answers a question a code generator always raises, which is whether the generated code will compile against the libraries you have. Compatible library versions are listed in COMPATIBILITY.md, and the README points at it explicitly. That file is the one to read before you commit to the tool, because a generator that targets a version of http4s different from the one in your build will produce code that does not compile, and the mismatch surfaces as a confusing set of errors rather than as a clear message.

The module structure, and why it is drawn this way

guardrail is modularized, using `sbt-version-policy` to ensure binary compatibility between dependent modules. That is the tool that lets a module declare that it depends on another module's API and holds that dependency stable across versions.

The dependency chain in the README is a table of modules and their versions, and the shape of it explains the architecture.

At the base sits `guardrail-core`, which depends on nothing else in the list. `guardrail-java-support` and `guardrail-scala-support` both sit on top of core, and they are the shared language-specific layers. On top of java-support there are three modules: `guardrail-java-async-http`, which depends on java-support and java-async-http, and `guardrail-java-dropwizard`, which depends on java-support, java-async-http and java-dropwizard, and `guardrail-java-spring-mvc`, which depends on java-support alone.

On the Scala side, `guardrail-scala-akka-http`, `guardrail-scala-dropwizard` and `guardrail-scala-http4s` all depend on scala-support.

The final module is `guardrail-cli`, which depends on guardrail-core.

Two things about that structure are worth drawing out. The first is that the Java and Scala branches are genuinely separate, so the core is not doing both languages' work and neither branch depends on the other. The second is the asymmetry in the Java branch, where spring-mvc depends only on java-support while dropwizard additionally depends on java-async-http. That reflects the fact that Dropwizard's stack needs the async HTTP layer underneath it, while Spring MVC brings its own.

The layering also means the CLI is a thin front end over core rather than a separate implementation. That is what allows the plugins to be thin as well: they share the same generation logic as the command line tool, so a discrepancy between what the plugin produces and what the CLI produces would be a bug in one place rather than two implementations drifting apart.

The repository layout mirrors this. There is a `modules/` directory holding the published modules, a `src/` directory, a `project/` directory for the sbt build definition, a `build.sbt` at the root, and a `docs/` directory for the documentation site. There is also a `notes/` directory and a `support/` directory.

The project files, and what they say about working on it

The root of the repository is a mixture of a Scala build and a documentation site, and the file names describe the toolchain well.

For the build there is `build.sbt`, the sbt build definition, plus `.sbtopts-default`, which is sbt's mechanism for shipping default options to every invocation, and `.jvmopts`, which sets the JVM options for the build. There is a `project/` directory for the sbt plugins and settings, and a `codecov.yml` for the coverage reporting.

For the code itself, `.scalafmt.conf` configures the Scala formatter, `.scala-steward.conf` configures the dependency update bot, and `.git-blame-ignore-revs` is the file that marks commits which only reformat code so that `git blame` can skip them. That last one is a small piece of engineering hygiene worth naming, because a formatter applied across a whole codebase produces a single enormous commit, and without the ignore list every line of the repository would be attributed to that commit.

For the documentation site, there is a `package.json` with a single dependency:

{
  "dependencies": {
    "docsify-cli": "^4.4.4"
  }
}

So the docs are served by docsify, and the npm package is only the command line tool for it. A `package-lock.json` sits beside it, and there is a `cli.sh` script at the root.

The repository also carries an `flake.nix` and a `flake.lock`, a `shell.nix`, and a `.envrc`. That is the Nix tooling, with the flake for a reproducible development environment and the shell file for direnv users. A `.ruby-version` file is present as well, which is presumably for a documentation or release script written in Ruby.

Then the documents that matter for anyone using the tool rather than hacking on it. `COMPATIBILITY.md` lists the compatible library versions. `MIGRATING.md` covers how to move between versions of guardrail itself, which matters because the generated code changes when the generator changes and your checked-in output has to be regenerated. `RELEASING.md` describes the release process and `CHANGELOG.md` records it. `CONTRIBUTING.md` provides an overview of how the project is structured, the expectations, and information around writing new integration tests.

The issue tracker carries labels for help wanted and good first issue, which is the standard signal that a project is open to outside contributions and to newcomers in particular.

Who uses it, and what to expect from a code generator

The adopters list is short and named: Avast and Twilio.

Two organisations with large API surfaces, which is the profile of a user for whom the generator pays off. A company with hundreds of endpoints and a maintained specification gets a return on the setup cost. A project with four endpoints does not, and would be better served by writing the handlers.

That is the general trade for a specification-driven generator, and it is worth being explicit about it because the appeal is obvious and the cost is less so. Generation gives you a server whose routing, decoding and model types match a document rather than a set of conventions that drift. The cost is a build step, a generated directory that developers are told not to edit, and a specification that becomes the source of truth, which means changing the API means changing the document and regenerating rather than changing the code.

The specification-first approach also has a documentation benefit that is easy to overlook. A server whose routes come from the specification cannot drift from that specification, because the specification is what produced the routes. The document stops being a promise about the server and becomes the thing that determines it.

The framework targets are where the generated code's style comes from. An akka-http server and a Spring MVC server have different shapes, different error handling conventions and different idioms for returning a response, and guardrail generates idiomatic code for each rather than a lowest common denominator. That is the argument for a generator with per-target modules rather than one with a single output mode.

For a newcomer, the practical path is the docs at guardrail.dev, then a look at COMPATIBILITY.md to see whether the versions of your HTTP library are supported, and then choosing the integration route that matches your build tool. The community channels are a Matrix room at `#guardrail:matrix.org` and a Gitter chat, both linked from the README.

Editorial conclusion

Adopt guardrail if your team already maintains an OpenAPI specification and wants the request handlers, models and routing to be generated from it rather than hand-written, since that is the whole purpose of the tool. Do not adopt it expecting it to generate a client, since it targets servers, and check first the COMPATIBILITY.md document, because the supported versions of each HTTP library are pinned there and a mismatch with your own dependency versions is the most likely source of friction.

Frequently asked questions

Official sources

1. guardrail-dev/guardrail on GitHub
2. License: MIT
3. Project website
4. README
5. Releases