cryostatio / cryostatio/cryostat
Document asynchronous job responses in OpenAPI contracts
- Dominant language
- Java
- Stars
- 57
- Forks
- 17
- Avg merge
- 15h 39m
- Merged PRs (30d)
- 42
Description
## Summary
Audit all HTTP endpoints that start asynchronous jobs through the `LongRunningRequest` pattern. Update their OpenAPI contracts to document the asynchronous response.
## Rationale
Some endpoints return a job ID with `202 Accepted` and a `text/plain` response body when work continues asynchronously. The generated OpenAPI specification can omit this response. Generated clients then have no contract for the job-ID response.
## Affected areas
- Resource methods that dispatch work through `LongRunningRequest` or the async job pattern.
- OpenAPI annotations on those resource methods.
- Generated `schema/openapi.yaml`.
## Required changes
1. Identify every endpoint that can return an asynchronous job response.
2. Document each asynchronous response with the correct status code, media type, and body schema.
3. Regenerate `schema/openapi.yaml`.
4. Keep synchronous success and failure response contracts unchanged unless the implementation requires a correction.
## Acceptance criteria
- Every asynchronous job endpoint has an OpenAPI response for its job-acceptance result.
- A `202 Accepted` response that returns a job ID declares `text/plain` and describes the job-ID body.
- `schema/openapi.yaml` matches the resource annotations.
- Tests or contract validation cover representative synchronous and asynchronous response paths.
## Backlinks
- Originating pull request: https://github.com/cryostatio/cryostat/pull/1706
- Originating review comment: https://github.com/cryostatio/cryostat/pull/1706#discussion_r3824107541
- Requested by: @andrewazores
Contributor guide
Research direction
Start by locating resource methods that use LongRunningRequest or the async job pattern, then inspect their OpenAPI annotations and the generated schema/openapi.yaml. Review existing tests or contract validation for representative synchronous and asynchronous paths. Done means every affected endpoint documents its 202 job-acceptance response with text/plain and a job-ID body, while the generated schema matches the annotations.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, openapi
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100