Use Test Examples as the placeholder for SwaggerUI?
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 28
- Forks
- 25
- Avg merge
- 4d 22h
- Merged PRs (30d)
- 20
Description
When going about learning a new endpoint I find myself going between the tests, what I think something should be, and guesswork/error responses.
If possible can we start placing (or go back) and place the test examples like this one: https://github.com/USACE/cwms-data-api/blob/5fd3d7e6d0ead40992bc47631916245575b4d017/cwms-data-api/src/test/java/cwms/cda/api/TextTimeSeriesControllerTestIT.java#L159
and its contents:
https://github.com/USACE/cwms-data-api/blob/develop/cwms-data-api/src/test/resources/cwms/cda/api/spk/text_ts_create_reg.json
That would go a long way in giving users an idea on how something might work. (Especially POST bodies)
Things I ran into just trying to run this endpoint were
- Realizing it should actually be a valid TSID (whoops)
- Making sure the time I set for it matches the interval I provided
- Realizing what all is actually required vs what the example provided
This way the tests also test every input as well (instead of doing the minimum)
Thought of this when trying to figure out
- #931
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with cwms-data-api/src/test/java/cwms/cda/api/TextTimeSeriesControllerTestIT.java and cwms-data-api/src/test/resources/cwms/cda/api/spk/text_ts_create_reg.json, then compare how SwaggerUI examples are currently provided. Use issue #931 for related context; done means representative test examples, especially POST bodies, are available to users in SwaggerUI.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, openapi
- Domain
- api, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100