docs: document GET /api/geschichten?documentId= filter in OpenAPI spec #794

New Issue

marcel · 2026-06-09T19:09:56+02:00

marcel commented

2026-06-09 19:09:56 +02:00

Context

GET /api/geschichten accepts a documentId query parameter that filters results to journeys containing that document (via a JPQL EXISTS subquery on JourneyItem). This filter was introduced as part of the journey editor feature (#750/#753).

The parameter is currently not declared in the controller's OpenAPI annotations, so:

It doesn't appear in the generated TypeScript API types
API consumers have no discoverable way to know it exists
The Swagger UI doesn't surface it

What needs to be done

In GeschichteQueryController (or wherever the GET /api/geschichten endpoint is declared), add @Parameter / @Operation OpenAPI annotations for the documentId query parameter, e.g.:

@Parameter(name = "documentId", description = "Filter to journeys containing this document", required = false, schema = @Schema(type = "string", format = "uuid"))

After annotating, run npm run generate:api in frontend/ to regenerate the TypeScript types so the parameter becomes part of the typed client.

Why this matters

Without documentation, the filter is only discoverable by reading the source. Future callers (e.g. a document detail page showing linked journeys) won't know to use it.

## Context `GET /api/geschichten` accepts a `documentId` query parameter that filters results to journeys containing that document (via a JPQL EXISTS subquery on `JourneyItem`). This filter was introduced as part of the journey editor feature (#750/#753). The parameter is currently not declared in the controller's OpenAPI annotations, so: - It doesn't appear in the generated TypeScript API types - API consumers have no discoverable way to know it exists - The Swagger UI doesn't surface it ## What needs to be done In `GeschichteQueryController` (or wherever the `GET /api/geschichten` endpoint is declared), add `@Parameter` / `@Operation` OpenAPI annotations for the `documentId` query parameter, e.g.: ```java @Parameter(name = "documentId", description = "Filter to journeys containing this document", required = false, schema = @Schema(type = "string", format = "uuid")) ``` After annotating, run `npm run generate:api` in `frontend/` to regenerate the TypeScript types so the parameter becomes part of the typed client. ## Why this matters Without documentation, the filter is only discoverable by reading the source. Future callers (e.g. a document detail page showing linked journeys) won't know to use it.

marcel added the P3-later documentation labels 2026-06-09 19:10:11 +02:00

marcel referenced this issue

2026-06-09 19:10:47 +02:00

feat(journey-editor): JourneyEditor frontend — issue #753 #792

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: marcel/familienarchiv#794