[
https://issues.apache.org/jira/browse/UNOMI-963?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Serge Huber updated UNOMI-963:
------------------------------
Description:
h2. Summary
Enrich Apache Unomi's *live* OpenAPI document (CXF {{OpenApiFeature}}) with
high-quality documentation derived from *existing* Java + Javadoc—without
scraping HTML, without duplicating prose into Swagger
{{@Schema(description=...)}} annotations, and without losing
OSGi/dynamic-deployment accuracy.
Primary consumers: human developers (Swagger UI, manuals), {{unomi-ui}} /
{{inoyu-ui}}, OpenAPI-driven clients, and AI agents that need typed, linked
contracts (not empty {{application/json: {}}}/{{default}} responses).
Related (not a duplicate): [UNOMI-899] (replace jaxrs-analyzer / CXF OpenAPI
generation). That work covers *how* the live spec is generated; this ticket
covers *documentation completeness* of that generation.
----
h2. Problem
The live spec ({{GET /cxs/openapi.json}}) and committed snapshots under
{{unomi-rest-api-tests}} are path-complete but documentation-poor:
* Methods returning {{javax.ws.rs.core.Response}} often show empty response
bodies even when the wire JSON is a typed DTO (e.g. {{TenantUsage}},
{{TenantEventPurgeResult}}).
* Responses are overwhelmingly a single {{default}} entry; named
{{200}}/{{400}}/{{401}}/{{404}}/{{500}} are missing.
* Schemas that *are* emitted from concrete return types have property
names/types but **no** field descriptions (Javadoc is not available at runtime
in CXF/swagger-core).
* Stock CXF {{JavaDocProvider}} scrapes *generated Javadoc HTML*—brittle across
JDK versions and unsuitable as a long-term approach.
* Mass {{@Operation}}/{{@Schema(description=...)}} would *duplicate* existing
Javadoc and drift.
Historical note: Miredot previously gave build-time, Javadoc-based docs but did
not model Unomi's *dynamically deployed* JAX-RS surface well. CXF is correct
for "what this Karaf instance registered"; build-time tools are correct for
"what the sources say." We need both.
----
h2. Inventory baseline (server/unomi, JAX-RS)
Static scan of {{src/main/java}} ({{@Path}} + HTTP verbs; abstract router CRUD
expanded):
|| Metric || Count ||
| HTTP operations | *181* (180 unique method+path; {{GET /profiles/export}}
overloaded twice) |
| Returning {{Response}} | *31* (highest schema risk) |
| JAX-RS resource classes | ~28 |
| Maven REST-ish modules | 8 |
|| Path prefix || Ops || Module ||
| {{/profiles}} (+ personas, sessions, properties, export) | 37 | {{rest}} |
| {{/definitions}} | 16 | {{rest}} |
| {{/campaigns}}, {{/rules}}, {{/segments}}, {{/privacy}} | 10 each | {{rest}}
/ privacy |
| {{/tenants}} | 9 | {{rest}} (3.1) |
| {{/scoring}} | 8 | {{rest}} |
| {{/goals}} | 7 | {{rest}} |
| {{/jsonSchema}} | 6 | json-schema ext |
| {{/lists}} + {{/userList}} | 5+1 | lists-ext + {{rest}} |
| {{/tasks}} | 5 | {{rest}} (3.1) |
| {{/exportConfiguration}}, {{/importConfiguration}} | 5 each | router-rest |
| {{/geonames}} | 5 | geonames |
| {{/events}}, {{/query}}, {{/scopes}} | 4 each | {{rest}} |
| {{/context.json}}, {{/context.js}}, {{/eventcollector}}, {{/cluster}} | 3
each | {{rest}} |
| {{/client}}, {{/groovyActions}}, {{/sfdc}} | 2 each | rest / groovy /
salesforce |
| {{/patches}}, {{/test/ping}} | 1 each | {{rest}} |
|| Maven module || Ops ||
| {{rest}} | 141 |
| {{extensions/privacy-extension/rest}} | 10 |
| {{extensions/router/router-rest}} | 10 |
| {{extensions/json-schema/rest}} | 6 |
| {{extensions/geonames/rest}} | 5 |
| {{extensions/lists-extension/rest}} | 5 |
| {{extensions/groovy-actions/rest}} | 2 |
| {{extensions/salesforce-connector/rest}} | 2 |
*Not* JAX-RS (document separately): servlet {{GET /health/check}}
({{extensions/healthcheck}}).
Coverage denominator for this ticket: inventory rows matching JAX-RS ops / 181.
Progress = enrichment packs covering those ops.
----
h2. Goals
# Live OpenAPI remains *deployment-accurate* (CXF reflects OSGi-registered
resources only).
# Enrichment packs are generated at *build time* from Java + Javadoc (and
JAX-RS annotations)—*no HTML scrape*.
# Prose is *not* duplicated into Swagger description annotations; Javadoc stays
the human source of truth.
# OpenAPI becomes useful for humans *and* agents: summaries, param docs, named
statuses, {{$ref}} schemas, property descriptions, stable operation keys.
# Per-bundle packs so optional extensions contribute docs only when installed.
----
h2. Non-goals
* Mass {{@Schema(description=...)}} / {{@Operation(summary=...)}} copying
Javadoc.
* Using CXF {{JavaDocProvider}} HTML scraping in production.
* Replacing CXF {{OpenApiFeature}} with a build-time-only OpenAPI as the sole
live API.
* Breaking HTTP wire contracts (paths, methods, status semantics, JSON shapes).
* Forcing {{/health/check}} into CXF JAX-RS OpenAPI.
* Documenting GraphQL or non-REST surfaces in this ticket.
----
h2. Architecture
{code}
Maven (per JAX-RS module)
→ JavaParser (or equivalent) on .java sources
→ META-INF/unomi/openapi-doc.json (enrichment pack)
packaged in OSGi bundle
Runtime
→ Discover packs from *installed* bundles (BundleTracker /
ClassLoader.getResources)
→ UnomiJsonDocumentationProvider implements
org.apache.cxf.jaxrs.model.doc.DocumentationProvider
→ OpenApiCustomizer.setJavadocProvider(provider)
→ Subclass/customize OpenApiCustomizer for response $refs + schema property
docs
→ OpenApiFeature serves complete /cxs/openapi.json
{code}
*CXF {{DocumentationProvider}} SPI* (already on {{OpenApiCustomizer}}):
|| SPI || OpenAPI field ||
| {{getMethodDoc}} | {{operation.summary}} / description |
| {{getMethodParameterDoc}} | {{parameter.description}} |
| {{getMethodResponseDoc}} | success response description |
| {{getClassDoc}} | tag description (if {{replaceTags}}) |
That SPI alone does *not* fix empty {{Response}} schemas or DTO property
docs—those need the customizer merge from the same JSON.
----
h2. Build-time extraction (high quality)
*Dual extract* from the same sources:
# *Structure*: {{@Path}}, HTTP verb, {{@*Param}}, return types, generics
({{PartialList<T>}}, etc.), Jackson visibility.
# *Meaning*: class/method/field Javadoc, {{@param}} (match by *name*),
{{@return}}, {{@throws}}.
Optional thin machine tags *only* where inference is ambiguous (do not restate
essays), e.g.:
{code}
@unomi.status 200 {@link TenantUsage}
@unomi.status 404 empty
@unomi.status 400 unsupported period
{code}
Especially required for multi-status bodies (e.g. {{purgeTenantEvents}}: 200
and 500 share {{TenantEventPurgeResult}}).
JSON packs should carry OpenAPI-like fragments (operations + schemas with
property descriptions), keyed by stable {{GET /path}} and/or
{{className#methodName}}.
----
h2. Compatibility
Documentation-only (plus optional signature cleanups that preserve wire
behavior). Especially: do *not* collapse purge {{200}}/{{500}} into a single
success code.
----
h2. Phased delivery
|| Phase || Scope || Notes ||
| *0 - Spike* | {{TenantEndpoint}}, {{TaskEndpoint}}, {{TenantUsage}} / purge
DTOs | Must prove pipeline; early 3.1 candidate |
| *1 - Core* | Remaining {{rest}} module (~141 ops) | Largest surface |
| *2 - Common extensions* | privacy, lists, json-schema | Often installed |
| *3 - Optional extensions* | geonames, groovy, router, sfdc | Validates
dynamic discovery |
| *4 - Hardening* | CI gates, snapshot regen, UI consumer notes | Release
hygiene |
*Release intent:* Phase 0 should try to land in *3.1* if the spike succeeds;
Phases 1-4 may complete in 3.1 or slip to *3.2* without blocking spike
learnings. Update fixVersion(s) when decided.
----
h2. Acceptance criteria / definition of done
h3. Pipeline
* [ ] Maven Mojo (or equivalent) extracts JAX-RS + Javadoc into a versioned
JSON pack schema.
* [ ] Packs emitted as {{META-INF/unomi/openapi-doc.json}} (name TBD) inside
REST OSGi bundles.
* [ ] Runtime discovery loads packs only from *installed* bundles.
* [ ] {{DocumentationProvider}} implementation fills operation/param/response
*prose* from JSON.
* [ ] {{OpenApiCustomizer}} extension applies response {{$ref}}s and schema
property docs from the same JSON.
* [ ] Wired from {{RestServer}} (existing customizer).
h3. Coverage
* [ ] Inventory of public JAX-RS ops tracked (denominator ≈ 181); enrichment
coverage measurable per module.
* [ ] All {{Response}}-returning methods (31) have status + schema metadata in
packs.
* [ ] DTOs referenced by enriched responses appear under schemas with property
descriptions where Javadoc exists.
* [ ] {{/health/check}} documented outside CXF OpenAPI (or explicitly waived).
h3. Quality / CI
* [ ] Fail (or stage-warn→fail) if public {{@Path}} method lacks Javadoc
summary.
* [ ] Fail if {{@*Param}} lacks matching {{@param}}.
* [ ] Fail if {{Response}} method lacks status/schema map.
* [ ] Test/fixture: OpenAPI contains {{TenantUsage}} {{$ref}} and named
statuses for purge.
* [ ] Procedure to regenerate committed OpenAPI snapshot for
{{unomi-rest-api-tests}} / UI docs.
h3. Compatibility tests
* [ ] Existing REST integration tests pass (no wire regressions).
* [ ] Swagger UI usable on a full distribution for spike endpoints.
----
h2. Spike (Phase 0) - immediate implementation target
# Hand-written or Mojo-generated JSON for tenants/tasks.
# {{UnomiJsonDocumentationProvider}} + customizer schema merge.
# Verify live {{GET /cxs/openapi.json}}: summaries, param docs, {{TenantUsage}}
{{$ref}}, purge 200/400/404/500.
# Write short effort estimate for rolling Phases 1-4 into 3.1 vs 3.2.
----
h2. References
* {{RestServer.java}} — {{OpenApiFeature}} / {{OpenApiCustomizer}}
* CXF {{OpenApiCustomizer}} + {{DocumentationProvider}} — use SPI, *not* HTML
{{JavaDocProvider}}:
https://github.com/apache/cxf/blob/3.6.x-fixes/rt/rs/description-openapi-v3/src/main/java/org/apache/cxf/jaxrs/openapi/OpenApiCustomizer.java
* {{TenantEndpoint.java}}, {{TaskEndpoint.java}}, tenant DTOs under
{{unomi-api}}
* {{server/unomi-rest-api-tests/unomi-openapi-3.1.0.json}}
* Endpoint inventory (attach): method, path, class, java_method, return,
module, file — ~181 rows
* {{rest/README.md}} — historical Miredot note on {{rest-documentation}} branch
----
h2. Sub-tasks (suggested)
# Define JSON pack schema + conventions ({{@unomi.status}})
# Implement / evaluate JavaParser-based extraction Mojo
# Runtime {{DocumentationProvider}} + pack discovery
# {{OpenApiCustomizer}} schema/status merge
# Phase 0 spike (tenants/tasks)
# Phase 1 core {{rest}} coverage
# Phase 2-3 extensions
# CI gates + snapshot regen + consumer docs
was:
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}}
> 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-3.0.0, unomi-2.7.0, unomi-3.1.0
> Reporter: Serge Huber
> Assignee: Serge Huber
> Priority: Major
> Fix For: unomi-3.1.0
>
>
> h2. Summary
> Enrich Apache Unomi's *live* OpenAPI document (CXF {{OpenApiFeature}}) with
> high-quality documentation derived from *existing* Java + Javadoc—without
> scraping HTML, without duplicating prose into Swagger
> {{@Schema(description=...)}} annotations, and without losing
> OSGi/dynamic-deployment accuracy.
> Primary consumers: human developers (Swagger UI, manuals), {{unomi-ui}} /
> {{inoyu-ui}}, OpenAPI-driven clients, and AI agents that need typed, linked
> contracts (not empty {{application/json: {}}}/{{default}} responses).
> Related (not a duplicate): [UNOMI-899] (replace jaxrs-analyzer / CXF OpenAPI
> generation). That work covers *how* the live spec is generated; this ticket
> covers *documentation completeness* of that generation.
> ----
> h2. Problem
> The live spec ({{GET /cxs/openapi.json}}) and committed snapshots under
> {{unomi-rest-api-tests}} are path-complete but documentation-poor:
> * Methods returning {{javax.ws.rs.core.Response}} often show empty response
> bodies even when the wire JSON is a typed DTO (e.g. {{TenantUsage}},
> {{TenantEventPurgeResult}}).
> * Responses are overwhelmingly a single {{default}} entry; named
> {{200}}/{{400}}/{{401}}/{{404}}/{{500}} are missing.
> * Schemas that *are* emitted from concrete return types have property
> names/types but **no** field descriptions (Javadoc is not available at
> runtime in CXF/swagger-core).
> * Stock CXF {{JavaDocProvider}} scrapes *generated Javadoc HTML*—brittle
> across JDK versions and unsuitable as a long-term approach.
> * Mass {{@Operation}}/{{@Schema(description=...)}} would *duplicate* existing
> Javadoc and drift.
> Historical note: Miredot previously gave build-time, Javadoc-based docs but
> did not model Unomi's *dynamically deployed* JAX-RS surface well. CXF is
> correct for "what this Karaf instance registered"; build-time tools are
> correct for "what the sources say." We need both.
> ----
> h2. Inventory baseline (server/unomi, JAX-RS)
> Static scan of {{src/main/java}} ({{@Path}} + HTTP verbs; abstract router
> CRUD expanded):
> || Metric || Count ||
> | HTTP operations | *181* (180 unique method+path; {{GET /profiles/export}}
> overloaded twice) |
> | Returning {{Response}} | *31* (highest schema risk) |
> | JAX-RS resource classes | ~28 |
> | Maven REST-ish modules | 8 |
> || Path prefix || Ops || Module ||
> | {{/profiles}} (+ personas, sessions, properties, export) | 37 | {{rest}} |
> | {{/definitions}} | 16 | {{rest}} |
> | {{/campaigns}}, {{/rules}}, {{/segments}}, {{/privacy}} | 10 each |
> {{rest}} / privacy |
> | {{/tenants}} | 9 | {{rest}} (3.1) |
> | {{/scoring}} | 8 | {{rest}} |
> | {{/goals}} | 7 | {{rest}} |
> | {{/jsonSchema}} | 6 | json-schema ext |
> | {{/lists}} + {{/userList}} | 5+1 | lists-ext + {{rest}} |
> | {{/tasks}} | 5 | {{rest}} (3.1) |
> | {{/exportConfiguration}}, {{/importConfiguration}} | 5 each | router-rest |
> | {{/geonames}} | 5 | geonames |
> | {{/events}}, {{/query}}, {{/scopes}} | 4 each | {{rest}} |
> | {{/context.json}}, {{/context.js}}, {{/eventcollector}}, {{/cluster}} | 3
> each | {{rest}} |
> | {{/client}}, {{/groovyActions}}, {{/sfdc}} | 2 each | rest / groovy /
> salesforce |
> | {{/patches}}, {{/test/ping}} | 1 each | {{rest}} |
> || Maven module || Ops ||
> | {{rest}} | 141 |
> | {{extensions/privacy-extension/rest}} | 10 |
> | {{extensions/router/router-rest}} | 10 |
> | {{extensions/json-schema/rest}} | 6 |
> | {{extensions/geonames/rest}} | 5 |
> | {{extensions/lists-extension/rest}} | 5 |
> | {{extensions/groovy-actions/rest}} | 2 |
> | {{extensions/salesforce-connector/rest}} | 2 |
> *Not* JAX-RS (document separately): servlet {{GET /health/check}}
> ({{extensions/healthcheck}}).
> Coverage denominator for this ticket: inventory rows matching JAX-RS ops /
> 181. Progress = enrichment packs covering those ops.
> ----
> h2. Goals
> # Live OpenAPI remains *deployment-accurate* (CXF reflects OSGi-registered
> resources only).
> # Enrichment packs are generated at *build time* from Java + Javadoc (and
> JAX-RS annotations)—*no HTML scrape*.
> # Prose is *not* duplicated into Swagger description annotations; Javadoc
> stays the human source of truth.
> # OpenAPI becomes useful for humans *and* agents: summaries, param docs,
> named statuses, {{$ref}} schemas, property descriptions, stable operation
> keys.
> # Per-bundle packs so optional extensions contribute docs only when installed.
> ----
> h2. Non-goals
> * Mass {{@Schema(description=...)}} / {{@Operation(summary=...)}} copying
> Javadoc.
> * Using CXF {{JavaDocProvider}} HTML scraping in production.
> * Replacing CXF {{OpenApiFeature}} with a build-time-only OpenAPI as the sole
> live API.
> * Breaking HTTP wire contracts (paths, methods, status semantics, JSON
> shapes).
> * Forcing {{/health/check}} into CXF JAX-RS OpenAPI.
> * Documenting GraphQL or non-REST surfaces in this ticket.
> ----
> h2. Architecture
> {code}
> Maven (per JAX-RS module)
> → JavaParser (or equivalent) on .java sources
> → META-INF/unomi/openapi-doc.json (enrichment pack)
> packaged in OSGi bundle
> Runtime
> → Discover packs from *installed* bundles (BundleTracker /
> ClassLoader.getResources)
> → UnomiJsonDocumentationProvider implements
> org.apache.cxf.jaxrs.model.doc.DocumentationProvider
> → OpenApiCustomizer.setJavadocProvider(provider)
> → Subclass/customize OpenApiCustomizer for response $refs + schema property
> docs
> → OpenApiFeature serves complete /cxs/openapi.json
> {code}
> *CXF {{DocumentationProvider}} SPI* (already on {{OpenApiCustomizer}}):
> || SPI || OpenAPI field ||
> | {{getMethodDoc}} | {{operation.summary}} / description |
> | {{getMethodParameterDoc}} | {{parameter.description}} |
> | {{getMethodResponseDoc}} | success response description |
> | {{getClassDoc}} | tag description (if {{replaceTags}}) |
> That SPI alone does *not* fix empty {{Response}} schemas or DTO property
> docs—those need the customizer merge from the same JSON.
> ----
> h2. Build-time extraction (high quality)
> *Dual extract* from the same sources:
> # *Structure*: {{@Path}}, HTTP verb, {{@*Param}}, return types, generics
> ({{PartialList<T>}}, etc.), Jackson visibility.
> # *Meaning*: class/method/field Javadoc, {{@param}} (match by *name*),
> {{@return}}, {{@throws}}.
> Optional thin machine tags *only* where inference is ambiguous (do not
> restate essays), e.g.:
> {code}
> @unomi.status 200 {@link TenantUsage}
> @unomi.status 404 empty
> @unomi.status 400 unsupported period
> {code}
> Especially required for multi-status bodies (e.g. {{purgeTenantEvents}}: 200
> and 500 share {{TenantEventPurgeResult}}).
> JSON packs should carry OpenAPI-like fragments (operations + schemas with
> property descriptions), keyed by stable {{GET /path}} and/or
> {{className#methodName}}.
> ----
> h2. Compatibility
> Documentation-only (plus optional signature cleanups that preserve wire
> behavior). Especially: do *not* collapse purge {{200}}/{{500}} into a single
> success code.
> ----
> h2. Phased delivery
> || Phase || Scope || Notes ||
> | *0 - Spike* | {{TenantEndpoint}}, {{TaskEndpoint}}, {{TenantUsage}} / purge
> DTOs | Must prove pipeline; early 3.1 candidate |
> | *1 - Core* | Remaining {{rest}} module (~141 ops) | Largest surface |
> | *2 - Common extensions* | privacy, lists, json-schema | Often installed |
> | *3 - Optional extensions* | geonames, groovy, router, sfdc | Validates
> dynamic discovery |
> | *4 - Hardening* | CI gates, snapshot regen, UI consumer notes | Release
> hygiene |
> *Release intent:* Phase 0 should try to land in *3.1* if the spike succeeds;
> Phases 1-4 may complete in 3.1 or slip to *3.2* without blocking spike
> learnings. Update fixVersion(s) when decided.
> ----
> h2. Acceptance criteria / definition of done
> h3. Pipeline
> * [ ] Maven Mojo (or equivalent) extracts JAX-RS + Javadoc into a versioned
> JSON pack schema.
> * [ ] Packs emitted as {{META-INF/unomi/openapi-doc.json}} (name TBD) inside
> REST OSGi bundles.
> * [ ] Runtime discovery loads packs only from *installed* bundles.
> * [ ] {{DocumentationProvider}} implementation fills operation/param/response
> *prose* from JSON.
> * [ ] {{OpenApiCustomizer}} extension applies response {{$ref}}s and schema
> property docs from the same JSON.
> * [ ] Wired from {{RestServer}} (existing customizer).
> h3. Coverage
> * [ ] Inventory of public JAX-RS ops tracked (denominator ≈ 181); enrichment
> coverage measurable per module.
> * [ ] All {{Response}}-returning methods (31) have status + schema metadata
> in packs.
> * [ ] DTOs referenced by enriched responses appear under schemas with
> property descriptions where Javadoc exists.
> * [ ] {{/health/check}} documented outside CXF OpenAPI (or explicitly waived).
> h3. Quality / CI
> * [ ] Fail (or stage-warn→fail) if public {{@Path}} method lacks Javadoc
> summary.
> * [ ] Fail if {{@*Param}} lacks matching {{@param}}.
> * [ ] Fail if {{Response}} method lacks status/schema map.
> * [ ] Test/fixture: OpenAPI contains {{TenantUsage}} {{$ref}} and named
> statuses for purge.
> * [ ] Procedure to regenerate committed OpenAPI snapshot for
> {{unomi-rest-api-tests}} / UI docs.
> h3. Compatibility tests
> * [ ] Existing REST integration tests pass (no wire regressions).
> * [ ] Swagger UI usable on a full distribution for spike endpoints.
> ----
> h2. Spike (Phase 0) - immediate implementation target
> # Hand-written or Mojo-generated JSON for tenants/tasks.
> # {{UnomiJsonDocumentationProvider}} + customizer schema merge.
> # Verify live {{GET /cxs/openapi.json}}: summaries, param docs,
> {{TenantUsage}} {{$ref}}, purge 200/400/404/500.
> # Write short effort estimate for rolling Phases 1-4 into 3.1 vs 3.2.
> ----
> h2. References
> * {{RestServer.java}} — {{OpenApiFeature}} / {{OpenApiCustomizer}}
> * CXF {{OpenApiCustomizer}} + {{DocumentationProvider}} — use SPI, *not* HTML
> {{JavaDocProvider}}:
> https://github.com/apache/cxf/blob/3.6.x-fixes/rt/rs/description-openapi-v3/src/main/java/org/apache/cxf/jaxrs/openapi/OpenApiCustomizer.java
> * {{TenantEndpoint.java}}, {{TaskEndpoint.java}}, tenant DTOs under
> {{unomi-api}}
> * {{server/unomi-rest-api-tests/unomi-openapi-3.1.0.json}}
> * Endpoint inventory (attach): method, path, class, java_method, return,
> module, file — ~181 rows
> * {{rest/README.md}} — historical Miredot note on {{rest-documentation}}
> branch
> ----
> h2. Sub-tasks (suggested)
> # Define JSON pack schema + conventions ({{@unomi.status}})
> # Implement / evaluate JavaParser-based extraction Mojo
> # Runtime {{DocumentationProvider}} + pack discovery
> # {{OpenApiCustomizer}} schema/status merge
> # Phase 0 spike (tenants/tasks)
> # Phase 1 core {{rest}} coverage
> # Phase 2-3 extensions
> # CI gates + snapshot regen + consumer docs
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
