Known gaps in the reference
The API reference is generated from the services. It is as good as the code allows. These gaps are known.
- Summaries come from Java method names. The services have no
@Operationor@Tagannotations. An overlay inopenapi/overlays/supplies readable tags, summaries for the key operations, and authentication schemes. Other summaries are derived from method names and read as such. - Most responses say "200 OK". Response schemas are inferred where the method returns a typed object. Many methods return a
Response, so the body is not described. - No server URLs. The specs carry none, on purpose. Use the hosts in Networking and ingress.
- No "try it" panel. Production enforces real Keycloak tokens, and a documentation page should not invite anyone to paste credentials into a form.
- Auth routes live elsewhere.
POST /api/auth/token,/refreshand/logoutare in the hand-written Frontend routes spec, not in a service spec. They are served on the web hosts only. - Path prefixes and the ingress. The services declare paths such as
/api/v1/lms/.... The ingress sends each prefix to one service. A prefix that is not in the ingress is not reachable from outside, even if a service declares it.
Closing the first two gaps needs @Operation and response annotations in the services. That is a change to service code and was not part of this documentation work.
Source: docs-site/openapi/overlays/, docs-site/scripts/apply-overlays.mjs.