Update Java Spring Boot Documentation

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Creates or refreshes the Antora documentation site for a DDD/hexagonal Spring Boot service (Java or Kotlin, Maven or Gradle), deriving every page from the contracts, entities, configuration classes, and Micrometer calls that are actually in the repository.

Purpose

iru-update-java-springboot-documentation does double duty on purpose: the first run scaffolds the page set, and every later run updates it from the code — which is the only way documentation of this depth survives contact with an evolving service.

Its governing rule is that everything on these pages is derived from something in the repository. Where something genuinely cannot be derived — why a technology was chosen, what a use case is for, a business constraint — the skill writes an explicit TODO: marker naming what’s needed and from whom, and never writes plausible-sounding prose in its place. The stated reasoning: a confidently wrong architecture page is worse than an obviously incomplete one, because nobody re-checks it. The consolidated list of TODO: markers is the most useful part of its report.

It treats springboot-stack.yml as intent and the code as truth, so a database in the manifest with no adapter module — or an adapter for something the manifest doesn’t list — is reported as a finding about the repository rather than quietly reconciled.

The same discipline surfaces genuine defects as a side effect of documenting: an endpoint whose spec security doesn’t match its filter chain, an exception the code can throw but the spec doesn’t document, a property that looks dynamic but isn’t `@RefreshScope`d, a metric with unbounded tag cardinality, an index no query uses.

Language and build-tool variants

The skill reads project.language (java/kotlin) and project.buildTool (maven/gradle) from springboot-stack.yml (absent means Java and Maven) and confirms both against the disk, which wins on disagreement. For Kotlin, pages quote code as [source,kotlin], say KDoc where Java says Javadoc, and link the Dokka KDoc reference published under api/kdoc/ from the overview — one link when Gradle aggregates Dokka at the root, one per module on Maven. On Gradle there is no enforcer: module boundaries are described through the ArchUnit test plus the declared project(":…​") dependencies, and pages name ./gradlew commands (build, test, integrationTest, :boot:bootRun). Kotlin pages also say whether coroutines are in play. Java services keep the pages unchanged.

Unlike Setup Antora, which installs Mermaid only, this skill also wires Kroki — Mermaid handles flows and sequences, while Kroki adds PlantUML, C4, and ERD, which is what the architecture and database-model pages need. It flags that with the public Kroki server every diagram’s source text is sent to a third-party service at build time, and that a sensitive model warrants self-hosting.

With a Hilla frontend (frontend: hilla in the manifest) the service also has a user interface, so the skill adds a User interface section (see Building user interfaces): ui/index.adoc, ui/navigation.adoc built from the file-based routes under src/main/frontend/views/, one ui/screens/<View>.adoc per routed view and one ui/components/<Component>.adoc per reusable component, exactly as reference/ui-docs.md describes, including its screenshot synchronisation against the .ui-screenshots/ that the frontend’s Playwright UI tests produce. With frontend: none there is no UI section.

Purpose group

Spring Boot Service Bootstrap

Although grouped with the Spring Boot bootstrap family — it is the last sub-skill that orchestrator runs — this is the one member of that family intended to be re-run continuously, in the same spirit as Update Docs in Repository Maintenance.

Plugin

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

Invocation

/iru-update-java-springboot-documentation
/iru-update-java-springboot-documentation <page-or-area>

Inputs

Argument Required Description Default

<page-or-area>

No

Positional argument naming a single page or area to refresh: overview, architecture, use-cases, database-model, apis/rest, apis/grpc, apis/graphql, apis/messaging, configuration, or metrics.

Absent means every page

mode

No

key: value line, new or existing. Informational only: it never means "update silently".

None

on-existing

No

key: value line, ask, keep, update or replace. When set, applied to every existing page without asking (the warning is still printed). Any other key: value line is ignored.

ask

springboot-stack.yml

No

Read for the declared stack, as intent to be checked against the code rather than as truth, including its ci: block (enabled, pages), which Step 7 uses to decide where the API reference links point, and project.language/project.buildTool, which select the Java/Kotlin and Maven/Gradle wording.

springboot-stack.yml at the repository root

The codebase

Yes

The real source: apis/ contracts, application.usecase classes, persistence entities and migration files, the exception-mapping advice, the Stream bindings, every @ConfigurationProperties class and which carry @RefreshScope, and the Micrometer calls in infrastructure/metrics.

None — derived

Outputs

Before writing, the skill announces whether it is creating the page set from scratch or updating existing documentation (listing the pages found). For existing pages it asks once: Update (refresh derived parts, keep hand-written prose, list contradictions), Keep as is (only create missing pages and nav entries), Replace (regenerate every page, losing hand-written prose) or Stop.

  • An Antora site with Kroki installed alongside Mermaid and the playbook amended (kroki-fetch-diagram, kroki-server-url), plus an api-docs-url attribute in docs/antora.yml — resolved from the GitHub Pages API, the git remote, or a custom domain — through which every API page links to its generated reference. When the manifest says docs are not deployed to Pages (ci.pages: false or ci.enabled: false) no github.io api-docs-url is written: the API links are replaced by a pointer to the documentation workflow artifact (with ci.enabled: true) or by local-build instructions naming the Maven command (with ci.enabled: false), and the source contract link is kept.

  • index.adoc — the service overview: purpose, capabilities, dependencies, and pointers onward.

  • architecture.adoc — the module table and the two mechanisms enforcing it (the enforcer rules and the named ArchUnit test), the concurrency model and its consequences, a per-technology section, a Mermaid dependency diagram, a Kroki module-dependency diagram, and the cross-cutting concerns. Each downstream client’s section also names the contract it is generated from and records that the same contract drives the API mock standing in for that service in integration tests and local runs, so a reader knows where to add a response instead of inventing a fixture.

  • use-cases.adoc — one section per use case: what it does, its trigger, its ordered steps, the ports and hence adapters it touches, every exception it can raise and what the caller sees, and a Mermaid sequence diagram including the failure branch.

  • database-model.adoc — per collection/table/label: a field table (name, type, mandatory, indexed, constraints, default, description), the indexes and which query each serves, relationships, and a per-engine diagram. Read from the entities and the migrations, since indexes and constraints usually live in the latter.

  • apis/rest.adoc, apis/grpc.adoc, apis/graphql.adoc, apis/messaging.adoc — version summaries, entity/message field tables with descriptions, constraints and deprecations, and endpoint documentation including authorization and every error response. Each page carries a prominent link, near the top, to its own generated reference published on GitHub Pages — OpenAPI HTML from the REST page, protobuf HTML from the gRPC page, AsyncAPI HTML from the messaging page, and the SpectaQL reference plus optional Voyager schema graph from the GraphQL page — one per contract version, written as {api-docs-url}/<kind>/<version>/index.html and accompanied by a link to the source contract in the repository. The Voyager link is only written when graphql-voyager is actually pinned in the GraphQL docs toolchain, since a link to a page that was never generated is worse than no link. The generated HTML is not Antora content, so xref: cannot reach it; the shared api-docs-url attribute keeps every API page pointing at one base that a domain change updates in a single edit.

      The GraphQL page additionally documents the **endpoints** — the single `spring.graphql.path` every query and
  mutation `POST`s to, the WebSocket path for subscriptions, and the GraphiQL explorer path together with the
  profiles it is enabled in, since leaving that on in production exposes the whole schema. All of it is read from
  the `application*.yml` files rather than quoted from the defaults. The messaging page is derived from the AsyncAPI
  specification in `apis/messaging/` as well as the AVRO schemas, cross-checked against the Spring Cloud Stream
  bindings — the bindings are what the service actually does, the specification is what it claims to do, and a
  disagreement between them is reported as a finding about the repository. What justifies the page beyond the
  generated HTML is what the generator can't know: consumer groups, DLQ topics, the use case behind each message,
  and the registry's compatibility mode.
* `configuration.adoc` — the property table with default, "dynamically changeable" (Yes / restart required /
  redeploy required, derived from the annotations), a criticality flag marking the performance and availability
  levers usable as a fast mitigation during a degradation, and a legend.
* `metrics.adoc` — the metric table with type, every tag key and its possible values, cardinality risk flagged, and
  where to scrape and view them locally.
* With `frontend: hilla`: the `ui/` pages above plus a **User interface** entry in `nav.adoc`, and the screenshots they use
  copied into `images/ui/`, synchronised once after Step 11 and before the Step 12 build (changed images replaced,
  unreferenced ones deleted, `.ui-screenshots/` removed).
* For Kotlin services, a KDoc reference link on the overview and a short "Build, test and run" list using the
  Gradle or Maven commands of the detected variant.
* `nav.adoc` entries for every page created.
* A report stating whether the page set was created or updated, the Step 0 option chosen, and per page created /
  updated / replaced / kept as is (with Hilla: the `ui/` pages created/updated/removed and the screenshot synchronisation result, including states left "screenshot pending"), plus which `api-docs-url` variant and which language/build-tool variant was used.

Execution flow

flowchart TD A["Start /iru-update-java-springboot-documentation"] --> B["Step 0: Resolve scope; read the manifest\nas intent; detect Java/Kotlin and Maven/Gradle; announce scratch vs update;\ngather facts via the Explore agent"] B -- pages exist, user chooses stop --> STOP[Stop without changes] B -- pages exist --> B2["Update / Keep as is / Replace\n(or on-existing)"] B2 --> C B -- from scratch --> C["Step 1: Ensure the site exists"] C -- no docs/antora.yml --> D["Bootstrap via iru-setup-antora"] D --> E C --> E["Install Kroki; amend the playbook\nalongside Mermaid"] E --> F["Step 2: Create or update the page set\nand nav.adoc, preserving hand-written prose"] F --> G["Steps 3-11: derive each page —\noverview, architecture, use cases, database model,\nREST/gRPC/GraphQL/messaging APIs, configuration, metrics"] G -- fact not derivable --> H["Write an explicit TODO: marker;\nnever invent prose"] H --> G G -- frontend hilla --> G2["UI section: ui/ pages and screenshot sync\nper reference/ui-docs.md"] G2 --> I G --> I["Step 12: Build the site;\nfix broken xrefs, tables, diagram syntax"] I --> J["Verify every Mermaid and Kroki diagram\nactually rendered — a bad Kroki block\nbuilds without warning"] J --> K["Step 13: Report pages, all TODOs by page,\nand every code/spec discrepancy found"]

Dependencies

Invokes

  • Setup Antora — Step 1, only if docs/antora.yml is absent, to get the toolchain, playbook, and ROOT module in place before this skill adds Kroki and the service page set.

Invoked by

Also — and mainly — run standalone after any change to a contract, an entity, a configuration property, a metric, or a use case, since the pages are derived and go stale the moment the code moves.

Related agents

  • Explore (built-in) — used in Step 0 for the broad structural sweeps over the module tree, use cases, entities, and metrics, so only the specific files it identifies are read directly. See Agents.

  • general-purpose (built-in, Claude Code’s default) — one-off use in Step 1 to run Setup Antora mid-run when no Antora module exists yet.

Source

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