Location Levels Endpoint Broken Headers and Poor Date Labeling

[krowvin]

There appear to be two primary GET endpoints for using location levels within CDA:
Everything is done against this CDA instance: https://cwms-data.usace.army.mil/cwms-data

Namely :

and

Issues:

Poor labeling

1. In the first, "/levels/{level-Id}" an "effective-date" field is presented but no date format is suggested. We know that all of the dates follow the ISO date format or variations of it, but we should still label it in my opinion:

2. In the second, a more extensive begin and end, similar to that of timeseries, is presented with no format provided:

Header Handling

This could be a separate issue, but it IS related to the functionality of this endpoint and could be fixed in the same PR under the 'Fixing the levels endpoints".

That being said, if you are not VERY specific with how you request the levels the second endpoint mentioned here will not work. It is even broke with the default setup in the swagger page:

If you enter these values:

You get:

{
  "levels": [],
  "page": "MHx8bnVsbHx8MTAw",
  "page-size": 100
}

This is because for some reason it wants you to set the format to json, even though it says it defaults it to JSON.

But if you set it to JSON you get this error:

{
  "message": "Accept header and query parameter are both present, this is not supported.",
  "incidentIdentifier": "-1781528758146567219",
  "details": {}
}

Which I have seen in other places too...

But if you then take the curl command this produces and change accept: application/json to accept: */* it works:
curl "https://cwms-data.usace.army.mil/cwms-data/levels?level-id-mask=Yatesville.Elev.Inst.0.Top%20of%20Normal&office=LRH&unit=EN&begin=2025-01-03T00%3A00%3A00-06%3A00&end=2025-02-03T00%3A00%3A00-06%3A00&format=json" -H "accept: */*"

It appears the default media type within swagger of "application/json" does not play nice. Setting it to null/not selected in swagger UI lets the request work as well:

Issues

1. You must set format=json, even though it says this is default. Otherwise resultset is empty(?)
2. The header provided in the swagger page appears to be wrong, and you must set */* / not selected in swagger UI

Notes/ recommendations

I suggest we create an "example" block at the end of descriptions to provide a sample string/value. Then use those variables you have defined for various date strings and make sure those are concatenated into the end of any datetime fields.
Perhaps even have predefined examples to be placed for future/present fields?

I.e. in the annotation we would do "Example: 2025-02-03T00:00:00-06:00
With one defined example