Problem
The Swagger docs at /cwms-data/swagger-docs document the location level POST body as the base LocationLevel shape which makes it look like clients can only submit fields such as constant-value and cannot store seasonal location levels.
The API currently supports seasonal level writes when the body contains seasonal-values. In LevelsController.deserializeLocationLevel, CDA dispatches to SeasonalLocationLevel when seasonal-values is present, and the DAO stores those values through the normal location level store path.
Why this matters
A user trying to store a seasonal level from Swagger has no discoverable request example or schema for fields such as:
seasonal-valuesinterval-origininterval-monthsinterval-minutesinterpolate-string- per-seasonal-value
value, offset-months, and offset-minutes
This is especially confusing because the same endpoint accepts different mutually exclusive POST variants. A caller may only want to store a constant-value, while another caller may need seasonal-values, a seasonal-time-series-id, or a virtual level body.
Suggested improvement
May need to update javalin to support this?
Expose the alternate POST request body shapes in Swagger/OpenAPI so the endpoint documents the supported variants instead of only the base DTO. Ideally the request body would show separate examples/schemas for:
- constant location level (
constant-value)
- seasonal location level (
seasonal-values)
- time-series-backed seasonal location level (
seasonal-time-series-id)
- virtual location level
Notes
SeasonalLocationLevel requires office-id, location-level-id, level-date, and seasonal-values. interval- months and interval-minutes are mutually exclusive.
Problem
The Swagger docs at
/cwms-data/swagger-docsdocument the location level POST body as the baseLocationLevelshape which makes it look like clients can only submit fields such asconstant-valueand cannot store seasonal location levels.The API currently supports seasonal level writes when the body contains
seasonal-values. InLevelsController.deserializeLocationLevel, CDA dispatches toSeasonalLocationLevelwhenseasonal-valuesis present, and the DAO stores those values through the normal location level store path.Why this matters
A user trying to store a seasonal level from Swagger has no discoverable request example or schema for fields such as:
seasonal-valuesinterval-origininterval-monthsinterval-minutesinterpolate-stringvalue,offset-months, andoffset-minutesThis is especially confusing because the same endpoint accepts different mutually exclusive POST variants. A caller may only want to store a
constant-value, while another caller may needseasonal-values, aseasonal-time-series-id, or a virtual level body.Suggested improvement
May need to update javalin to support this?
Expose the alternate POST request body shapes in Swagger/OpenAPI so the endpoint documents the supported variants instead of only the base DTO. Ideally the request body would show separate examples/schemas for:
constant-value)seasonal-values)seasonal-time-series-id)Notes
SeasonalLocationLevelrequiresoffice-id,location-level-id,level-date, andseasonal-values.interval- monthsandinterval-minutesare mutually exclusive.