Redefine Vulnerabilities API scope params

Summary

The Vulnerabilities API includes an optional scope param, which can take values all or dismissed. The default scope is dismissed. As implemented, the default API behavior returns only non-dismissed vulnerabilities. !12076 (diffs)

Many people assume the value dismissed would include dismissed vulnerabilities and exclude non-dismissed vulnerabilities, which is the opposite of what it actually does. !16692 (comment 219435620)

Improvements

• Add scope value not_dismissed, which includes only vulnerabilities that have not been dismissed
• Make scope value not_dismissed the default value and behavior
• Update dismissed to return only vulnerabilities that have been dismissed OR deprecate the value

We should make this change to make the API behavior easier to understand. In other param values, (e.g. report_type=sast), the API call will include anything matching the provided value(s). This change would make the param and values behave similarly, by including vulnerabilities with the given status, rather than excluding them.

Risks

This is a breaking change, as it updates the default behavior of the API and flips the behavior of a param value. I'm comfortable with this risk, as the Vulnerability API is explicitly labeled as "alpha stage and unstable." I think the added clarity and consistency adds good value, as it aligns behavior with the most common assumption.

Involved components

gitlab/ee/lib/api/vulnerabilities.rb

gitlab/ee/app/finders/security/vulnerabilities_finder.rb

gitlab/ee/app/finders/security/pipeline_vulnerabilities_finder.rb

Documentation and specs.