Skip to main content

Unomi 3.1 · Developer experience

Richer OpenAPI docs from Javadoc

Unomi 3.1 ships an enriched /cxs/openapi.json — summaries, status codes, examples, and schema notes merged from endpoint Javadoc.

Stock CXF OpenAPI generation is a great skeleton and a thin reading experience: operation ids, parameter names, and “default response.” Unomi 3.1 ( UNOMI-963) keeps a single source of truth in Javadoc and merges richer documentation into the live OpenAPI document at runtime.

Javadoc to enrichment pack to CXF openapi.json pipeline

How the pipeline works

  1. Build time — a Maven Mojo scans JAX-RS sources and writes an enrichment pack (openapi-doc.json) into each REST module JAR
  2. Runtime — Unomi’s CXF OpenAPI customizer loads every pack on the classpath and merges summaries, parameters, named statuses, examples, and schema field docs into /cxs/openapi.json

Authors document once on the Java method / type; agents, Swagger UI, and humans all see the same result.

Capabilities

  • Build-time Mojo — scan JAX-RS sources; emit enrichment pack JSON into each REST module JAR
  • Multi-pack merge — runtime loader merges packs from core rest and extension modules
  • CXF OpenApiFeature customizer — merges into live /cxs/openapi.json (and Swagger UI)
  • Operation summary / description — from the first Javadoc sentences
  • Parameter docs — @param Java names remapped to @PathParam / @QueryParam values
  • Return / success docs — from @return
  • Named HTTP statuses — @api.status for realistic 2xx / 4xx / 5xx (not only “default response”)
  • Examples — @api.example on operations and on schema properties
  • Schema field docs — Javadoc on DTO fields (enums as string + values; maps document expected keys)
  • Request / response models — enrichment for types used by hot paths (tenants, context, profiles, rules, segments, privacy, extensions, …)
  • extraSourceRoots — document DTOs that live in a sibling api module
  • Servlet endpoints — optional enrichment for documented HttpServlet paths (class-level tags)
  • Single source of truth — no duplicate Swagger annotation tax on every method

Try it on a running 3.1 server

curl -u karaf:karaf http://localhost:8181/cxs/openapi.json | jq '.paths["/tenants/{tenantId}"].get'

Compare operation descriptions, response maps, and examples against a 2.x or early-3.0 baseline — the inventory stays stable; the documentation density is what changes.

Why publish this with 3.1

Unomi 3 kept the REST surface familiar for migrations. Enrichment makes that surface discoverable for contributors, customer engineers, and LLM / agent tooling that already prefer OpenAPI over tribal knowledge. It pairs with the manual and request tracing investments: docs you can read, traces you can run, schemas you can generate clients from.

Unomi 3.1 manual API stability / migrate UNOMI-963

← All posts