sergehuber opened a new pull request, #826:
URL: https://github.com/apache/unomi/pull/826
## Plain-language summary
Swagger / `/cxs/openapi.json` was thin: missing useful status descriptions,
examples, and accurate schema fields (e.g. wire names vs Java bean names). This
PR documents the REST API from existing Javadoc using the external
**openapi-enrich** toolkit (`dev.inoyu.openapi:*:0.1.0` on Maven Central), so
clients and Swagger UI get Tenant-quality OpenAPI without runtime behavior
changes.
## What changed
* **Build wiring:** `${openapi.enrich.version}` **0.1.0** (Central); Mojo on
`rest` + extension REST modules; embed `cxf-openapi-enricher` + model into
`unomi-rest`; `EnrichingOpenApiCustomizer` in `RestServer`.
* **Javadoc enrichment:** `@api.status` / `@api.example` across core
endpoints (context, events, profiles, rules, segments, privacy, mid/thin REST)
and extensions (geonames, lists, json-schema, router import/export, groovy,
SFDC, healthcheck).
* **Schema docs:** Field/examples on key models (Profile, Event,
Condition/Action wire `type`, Query/PartialList, Tenant, …); suppress transient
CXF props that were leaking into OAS.
* **No intentional API behavior change** — documentation / OpenAPI document
only.
## Reviewer guide
| Prefer reading first | Why |
|---|---|
| `rest/pom.xml`, root `pom.xml` | dependency + Mojo pin to Central `0.1.0` |
| `rest/.../RestServer.java` | customizer wiring |
| `rest/.../TenantEndpoint.java`, `ContextJsonEndpoint.java`,
`RulesServiceEndPoint.java` | exemplars for `@api.status` / `@api.example`
grammar |
| One extension, e.g. `extensions/geonames/rest/.../GeonamesEndPoint.java` |
same pattern outside `rest` |
Most of the remaining file list is **mechanical Javadoc**
(statuses/examples/schema fields) following those exemplars — review by
sampling prefixes rather than line-by-line.
**Intentionally not enriched:** `GET /api-docs/{resource}` (Swagger helper).
## Test plan
- [x] Live `/cxs/openapi.json` after deploy: **179/179 gold** excl.
`/api-docs` (statuses + examples); Condition/Action show wire `type` +
`parameterValues`
- [x] Toolkit resolves from Maven Central:
`dev.inoyu.openapi:cxf-openapi-enricher:0.1.0` (and model / maven-plugin)
- [ ] CI `mvn` build on this branch (plugin + enricher from Central)
- [ ] Spot-check Swagger UI: `/cxs/profiles`, `/cxs/rules`,
`/cxs/context.json`, `/cxs/geonames/...`
```bash
curl -u karaf:karaf http://localhost:8181/cxs/openapi.json | jq
'.paths["/rules/{ruleId}"].get.responses'
curl -sS -o /dev/null -w "%{http_code}\n" \
https://repo1.maven.org/maven2/dev/inoyu/openapi/cxf-openapi-enricher/0.1.0/cxf-openapi-enricher-0.1.0.pom
```
## References
* JIRA: [UNOMI-963](https://issues.apache.org/jira/browse/UNOMI-963)
* Toolkit: [dev.inoyu.openapi on Central](https://central.sonatype.com/) ·
coords `dev.inoyu.openapi:cxf-openapi-enricher:0.1.0`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
