USACE / USACE/cwms-data-api

Use Test Examples as the placeholder for SwaggerUI?

Open
#930 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

discussion-point documentation
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

  1. Realizing it should actually be a valid TSID (whoops)
  2. Making sure the time I set for it matches the interval I provided
  3. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.