USACE / USACE/cwms-data-api

Correctly describe regular expressions and regular expressions in the SwaggerUI and have Regular Expressions use .* and not *

Open
#1,579 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

There are a couple places: ForecastSpecController, TimeSeriesProfileInstanceCatalogController and TimeSeriesProfileParserCatalogController where parameters that accept regular expressions aren't documented as such. Any Controller parameter that accepts a regular expression should link to regexp.html in its description.

Futhermore "" isn't really a valid regular expression. The Oracle regex engine treats it as if it were "." but we shouldn't rely on that. We should use ".*" anywhere it gets fed into a regular expression.

There are some other places in our code where parameters are passed down into pl/sql procedures that do their own wildcard matching - unless specifically called out, those do not do regular expressions and likely do use "*"

If we have Controller parameters that are named incorrectly we should probably deprecate them and make a new parameter with the intended name. We have some helper methods to deal with this.

For example, ForecastSpecController could do something like this to check the new parameter and a deprecated parameter.

 String sourceEntityRegex = queryParamAsClass(ctx, 
                    new String[]{Controllers.SOURCE_ENTITY_MASK, Controllers.SOURCE_ENTITY}, 
                    String.class, WILDCARD_REGEX );

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 ForecastSpecController, TimeSeriesProfileInstanceCatalogController, and TimeSeriesProfileParserCatalogController, then search other controller parameters that accept regular expressions. Review their Swagger descriptions and the parameter names passed to queryParamAsClass; done means regex parameters link to regexp.html, regex defaults use .* rather than *, and PL/SQL wildcard parameters remain unchanged unless explicitly identified as regexes.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.