Transmission #060: OpenAPI Redoc + YAML/JSON on Jersey

Jersey: Redoc and packaged OpenAPI

Helerion’s OpenAPI spec lives at repo root openapi.yaml; Gradle already validates and generates JAX-RS from it. The Jersey stub (JERSEY_PORT, base /v1) now exposes interactive docs and raw spec mirrors:

• GET /v1 → 303 to /v1/docs (browser-friendly entry).
• GET /v1/docs → HTML shell that loads Redoc from the official CDN, with spec-url built from UriInfo so it tracks host/port and the v1 application path (no hard-coded /docs/yaml).
• GET /v1/docs/yaml → packaged openapi.yaml (application/yaml / text/yaml).
• GET /v1/docs/json → same document parsed with Jackson (YAML → JsonNode) as application/json.

processResources copies the resolved spec file into openapi.yaml on the classpath so the fat JAR always carries the spec alongside Flyway assets.

OpenApiDocsIntegrationTest (same “live Jersey” expectations as ItemsApiIntegrationTest) asserts YAML/JSON bodies contain openapi and that GET /v1 redirects into /docs.

PDD scaffold for the idea (optional follow-on): .agents/planning/2026-05-06-openapi-redoc-jersey/ (rough-idea.md, idea-honing.md, empty research/, design/, implementation/).

Jersey port root → docs

JerseyServer now starts Grizzly with createHttpServer(..., false), registers a small Grizzly HttpHandler at HttpHandlerRegistration.ROOT, then starts the listener. GET / HEAD on / (same port as Jersey, default 8082) respond 303 with Location: /v1/docs; other methods at / get 405. Jersey remains mounted only under /v1, so /v1/items and the rest are unchanged. OpenApiDocsIntegrationTest asserts Location is exactly /v1/docs.

PDD / idea honing: Q1 (public docs + root / → /v1/docs); Q2 (CDN vs self-host) → public CDN.

PDD: detailed design (Step 6)

Authored .agents/planning/2026-05-06-openapi-redoc-jersey/design/detailed-design.md as a standalone spec: overview, consolidated requirements table, architecture and sequence mermaid diagrams, components (JerseyServer, JerseyResourceConfig, ApiDocsResource, Gradle packaging, integration tests), logical “data” artifacts, error-handling matrix, testing strategy, and appendices (tech choices, alternatives, constraints). Documents as-built alignment with the current server tree. Next PDD step is implementation plan (implementation/plan.md) if you want a formal checklist for follow-on work—or explicit sign-off to treat the feature done.