USACE / USACE/cwms-data-api

Set examples in the placeholder and in the swagger description of each endpoint

Open
#911 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

priority:high
Dominant language
Java
Stars
28
Forks
25
Avg merge
4d 22h
Merged PRs (30d)
20

Description

In the Swagger UI the input box has the same placeholder as the label name.

I wanted to bring the question up if we could use an actual value for the placeholder

For example

Timeseries would have

Name: [ KEYS.Elev.Inst.1Hour.0.Ccp-Rev ] 
Office: [ SWT ] 
Begin: [ 2022-10-11T00:00:00-05:00 ] 

It might also be worthwhile to make sure there is an example block beneath each of the text?

I know we have example payload but those tend to show string (I think we talked about this once before)

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 by locating the OpenAPI endpoint definitions that generate the Swagger UI and reviewing the existing example payloads that currently render values as string. Check how placeholders, field descriptions, and example blocks are represented across the endpoints. Done means the relevant inputs show useful actual examples and each endpoint's text or payload examples no longer relies on generic string values.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.