cryostatio / cryostatio/cryostat

Document asynchronous job responses in OpenAPI contracts

Open
#1,748 0 comments 0 reactions 0 assignees View on GitHub
bug docs
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.