Setup Java Spring Boot APIs

iru-setup-java-springboot-apis enforces two invariants:

The language and build tool come from springboot-stack.yml’s `project.language (java or kotlin, absent means java) and project.buildTool (maven or gradle, absent means maven; gradle is only valid with kotlin, and a manifest pairing it with java makes the skill stop and report). The contracts in apis/ are identical in all three combinations — a contract never depends on the language implementing it; only the generator changes:

On Gradle every plugin, protoc artifact and library version goes in gradle/libs.versions.toml (resolved live, protobuf and gRPC aligned to the versions the Spring Boot BOM manages), and modules apply plugins with alias(libs.plugins.…) and no inline version, mirroring the Maven "no <version> in module poms" rule.

The setting that makes the REST generator safe to re-run is interfaceOnly=true: the generator owns the interfaces and DTOs, and the hand-written @RestController implements them, so mvn generate-sources (or the Gradle equivalent) can never overwrite real logic. Without it the generator emits controllers and every regeneration becomes a merge conflict.

Contracts are versioned in the filename and in the path inside the contract — an OpenAPI spec’s paths carry /v1/…​, a protobuf file declares package <service>.v1, an AVRO namespace ends in .v1, and a GraphQL SDL, which has no in-band version at all, is versioned by filename and by the package its types generate into — so a breaking change means a new v2 file alongside the v1 one, with both generating and both served until v1 is retired.

apis/messaging/ is the one contract directory holding two kinds of file. The AVRO schemas define the message payloads and are what avro-maven-plugin compiles into Java; an AsyncAPI specification alongside them defines the interface — which topics exist, in which direction the service uses each one, which message each carries, and on which broker. Nothing is generated from the AsyncAPI file except documentation, but without it the AVRO schemas describe messages with no discoverable topics. Keeping both in one directory is deliberate: a new event means a new .avsc and a new channel, and a reviewer should see both in the same diff.

HTML documentation is generated alongside the code — the OpenAPI html2 generator, protoc-gen-doc for protobuf, spectaql (plus an optional GraphQL Voyager schema graph) for the GraphQL SDL, and @asyncapi/html-template for messaging — into target/generated-docs/, where the build workflow publishes it to GitHub Pages next to the Antora site, so the documentation pages link to it rather than duplicating the endpoint list by hand.

GraphQL needs that treatment explicitly because graphql-codegen-maven-plugin generates code, not documentation: without a second toolchain the one contract-first API in the reactor would publish nothing. It follows the same shape as messaging — an npm toolchain pinned beside the contract in apis/graphql-server/docs/, driven from the Maven build by frontend-maven-plugin at generate-resources, with a graphql.docs.skip escape hatch for offline builds. SpectaQL is the reference someone reads to integrate (oneFile: true yields one self-contained index.html); Voyager is the interactive graph that answers how the types connect, and is optional because it roughly doubles the published bytes. Both read the SDL directly, so neither needs a running service or an introspection endpoint in CI.

The AsyncAPI documentation is produced by the official, non-Maven AsyncAPI CLI, driven from the Maven build via frontend-maven-plugin so mvn generate-resources yields it with no globally installed Node. The specification is written against the current AsyncAPI version (3.1.0 at the time of writing); the skill confirms what’s current rather than hardcoding it, since asyncapi validate reports asyncapi-latest-version informationally whenever a newer one exists. That same validation runs as its own execution ahead of generation, and it is a real gate rather than decoration: it resolves and type-checks the referenced .avsc files, so a malformed document, a $ref to a missing schema, or an .avsc that isn’t valid AVRO all fail the build instead of yielding a page with empty payload tables. An out-of-date asyncapi: version, by contrast, is reported only as information — so a new specification release can never break the build on its own.

The skill announces whether it is creating the API layer from scratch or updating an existing one (listing the contract files, documentation toolchains and generator executions that exist). For each pre-existing artifact it owns it warns and asks Update (Recommended) / Keep as is / Replace, unless on-existing pre-answers. Existing contract files are never rewritten by Update, since a contract is the service’s real API rather than a template; Replace on a contract swaps a real API definition for a placeholder, so it is only offered after saying so explicitly and is never recommended.

Spring Boot Service Bootstrap

Shipped by the iru-springboot plugin of the ai-catalog marketplace (install with /plugin install iru-springboot@ai-catalog; see Plugins).

Optionally with args (stack-file:, mode:, on-existing: lines), as passed by iru-setup-java-springboot.

The generated files' bytes come from template files under templates/ (and, where a template needs variant-specific notes, reference/) in .claude/skills/iru-setup-java-springboot-apis/; the skill reads only the files for the variant it resolved, not the whole set, which keeps its SKILL.md small.

SKILL.md on GitHub — the file this page was generated from.