Serge Huber created UNOMI-963:
---------------------------------
Summary: Improve OpenAPI completeness with Swagger annotations
Key: UNOMI-963
URL: https://issues.apache.org/jira/browse/UNOMI-963
Project: Apache Unomi
Issue Type: Improvement
Components: unomi(-core)
Affects Versions: unomi-2.7.0, unomi-3.0.0, unomi-3.1.0
Reporter: Serge Huber
Assignee: Serge Huber
Fix For: unomi-3.1.0
h2. Summary
Prototype enriching the live OpenAPI document generated by CXF
{{OpenApiFeature}} with Swagger/OpenAPI 3 annotations so response schemas and
status codes are accurate. Goal for 3.1: validate the approach on a small
surface (tenants/tasks) and decide whether a partial landing (or fuller pass)
still fits the release.
h2. Problem
The live spec ({{GET /cxs/openapi.json}}) and committed snapshots under
{{unomi-rest-api-tests}} are path-complete but documentation-poor:
* Many endpoints returning {{javax.ws.rs.core.Response}} show empty response
bodies ({{application/json: {}}}) even when the runtime returns typed JSON
(e.g. {{TenantUsage}}, {{TenantEventPurgeResult}}).
* All responses use a generic {{default}} status; no named 200/400/404/500.
* Schemas that *are* emitted (from concrete return types) have property
names/types but no field descriptions (Javadoc is not exported at runtime).
This limits usefulness for {{unomi-ui}} / {{inoyu-ui}} and any OpenAPI-driven
clients.
Related (not a duplicate): [UNOMI-899] covers replacing jaxrs-analyzer with CXF
OpenAPI generation — generation works; this ticket is about *completeness of
the generated content*.
h2. Prototype scope (3.1 candidate)
# Add {{swagger-annotations}} dependency if not already compile-visible.
# Annotate {{TenantEndpoint}} + {{TaskEndpoint}} with {{@Operation}},
{{@APIResponses}} / {{@APIResponse}}, {{@Parameter}}.
# Use {{@Schema(implementation = ...)}} on {{Response}} methods so models enter
{{components/schemas}} (especially {{TenantUsage}}, {{TenantEventPurgeResult}}).
# Optionally add {{@Schema(description=...)}} on those few DTOs to prove field
prose (Javadoc alone will not appear).
# Keep {{purgeTenantEvents}} as {{Response}} with multi-status docs (200 and
500 share the same body).
# Regenerate / compare live OpenAPI vs snapshot; update
{{unomi-openapi-3.1.0.json}} if we land the change.
# Confirm {{unomi-rest-api-tests}} still pass (no HTTP wire changes).
h2. Out of scope for the prototype
* Annotating the entire REST surface (~179 ops) — if promising, follow-up for
remaining packages.
* Changing HTTP paths, status semantics, or JSON shapes.
* Build-time Javadoc → OpenAPI pipeline (would be a separate effort).
h2. Acceptance criteria (prototype)
* [ ] {{GET /tenants/{tenantId}/usage}} documents 200 with {{TenantUsage}}
schema (schema present in {{components/schemas}}).
* [ ] {{POST /tenants/{tenantId}/purge/events}} documents 200/400/404/500 with
correct bodies where applicable.
* [ ] {{GET /tenants/{tenantId}}} and task GET endpoints document concrete
response schemas (via annotations and/or safe typed returns).
* [ ] Live OpenAPI and Swagger UI show summaries + named status codes for
annotated methods.
* [ ] No existing REST integration test failures attributable to wire changes.
* [ ] Short write-up: effort estimate to extend to remaining endpoints for 3.1
vs defer remainder.
h2. Compatibility
Documentation-only (and optional signature refactors that preserve wire
behavior). Especially: do not collapse purge 200/500 into a single success code.
h2. References
* {{RestServer.java}} — {{OpenApiFeature}}
* {{TenantEndpoint.java}}, {{TaskEndpoint.java}}
* {{server/unomi-rest-api-tests/unomi-openapi-3.1.0.json}}
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
