feat: display numeric constraints for path and query parameters #10586

SiddarthaKarri · 2025-10-02T10:35:36Z

feat: display numeric constraints for path and query parameters

Description

This PR adds support for displaying numeric constraints (minimum, maximum, exclusiveMinimum, exclusiveMaximum) for path and query parameters in Swagger UI documentation. Previously, these constraints were only visible for request body schemas but not for parameters, making it unclear to API consumers what numeric boundaries are enforced.

The implementation adds a formatNumericConstraints() function that formats constraints with proper mathematical symbols and displays them in the parameter description area alongside existing parameter information like default values and examples.

Motivation and Context

This change is required to improve API documentation clarity and developer experience. API consumers need to see parameter constraints to understand what values are valid without having to refer to external documentation or discover limits through trial and error.

Fixes #10562

How Has This Been Tested?

Manual Testing:

Tested with various OpenAPI 3.0 specifications containing different constraint combinations
Verified constraints display correctly in both documentation view and "Try it out" mode
Tested with Swagger 2.0 specifications to ensure backward compatibility
Confirmed existing parameter functionality (default values, examples, enum values) remains unchanged

Test Environment:

Node.js version: Latest
Browser testing: Chrome, Firefox
OpenAPI versions: 2.0 and 3.0

Automated Testing:

All existing unit tests continue to pass
Added comprehensive unit tests covering all constraint types
Edge cases tested include missing constraints, mixed constraint types, and malformed schemas

Screenshots (if appropriate):

The constraints now appear in parameter documentation as:

Before: Only showed parameter name, type, and description
After: Shows constraints like "Constraints: ≥ 1" or "Constraints: [1, 100]" below the description

Examples of constraint display:

minimum: 1 → "≥ 1"
maximum: 100 → "≤ 100"
exclusiveMinimum: 0 → "> 0"
minimum: 1, maximum: 100 → "[1, 100]"

Checklist

My PR contains...

No code changes (src/ is unmodified: changes to documentation, CI, metadata, etc.)
Dependency changes (any modification to dependencies in package.json)
Bug fixes (non-breaking change which fixes an issue)
Improvements (misc. changes to existing features)
Features (non-breaking change which adds functionality)

My changes...

are breaking changes to a public API (config options, System API, major UI change, etc).
are breaking changes to a private API (Redux, component props, utility functions, etc.).
are breaking changes to a developer API (npm script behavior changes, new dev system dependencies, etc).
are not breaking changes.

Documentation

My changes do not require a change to the project documentation.
My changes require a change to the project documentation.
If yes to above: I have updated the documentation accordingly.

Automated tests

My changes can not or do not need to be tested.
My changes can and should be tested by unit and/or integration tests.
If yes to above: I have added tests to cover my changes.
If yes to above: I have taken care to cover edge cases in my tests.
All new and existing tests passed.

Add formatNumericConstraints function to display minimum, maximum, exclusiveMinimum, and exclusiveMaximum constraints for path and query parameters in the documentation. - Add constraint formatting with proper mathematical symbols (, , >, <) - Support range notation for combined constraints [min, max], (min, max) - Display constraints in parameter description area - Add comprehensive unit tests for all constraint types - Work in both documentation view and Try it out mode

glowcloud · 2025-10-03T11:04:46Z

Hi @SiddarthaKarri,

Thanks for your contribution!

From what I’m seeing formatNumericConstraints is an extension of stringifyConstraintNumberRange with additional handling of Immutable objects. This could instead be done by exposing this function in a similar way it was done here. Additionally, this function only handles constraints for OpenAPI 3.1. In OpenAPI 2.0 and 3.0, exclusiveMinimum and exclusiveMaximum come from JSON Schema Draft 4/5, where they are of type boolean, not number.

I would recommend the following steps for handling these cases:

Create a separate function for OpenAPI 2.0 and 3.0 in JSON Schema Draft 5 plugin and expose it to the system through fn.
Expose the existing function in JSON Schema 2020-12 plugin through fn.jsonSchema202012.
For OpenAPI 3.1, overwrite the function exposed in JSON Schema Draft 5 plugin with handling transformation from Immutable, as it was done here.
In ParameterRow, use the function directly through the now exposed fn.stringifyConstraintNumberRange. fn should already be passed down to the component, as I can see it is used e.g. here.

Optional steps:

Add handling of other constraints. We can already create constraints for OpenAPI 3.1 with the existing functions. For OpenAPI 2.0 and 3.0, additional functions might be required, as the constraints might differ.
Add the display of constraints for request bodies with media type application/x-www-form-urlencoded and multipart/*. As can be seen in the screenshot, we also don't display constraints there.

…straints

@glowcloud

- Replace custom formatNumericConstraints with plugin-exposed functions - Add stringifyConstraintNumberRange to json-schema-5 plugin for OpenAPI 2.0/3.0 - Expose existing stringifyConstraintNumberRange from json-schema-2020-12 plugin for OpenAPI 3.1 - Update ParameterRow to use appropriate constraint function based on OpenAPI version - Handle Immutable to plain object conversion for OpenAPI 3.1 - Add comprehensive unit tests for both constraint functions and component integration Addresses feedback from @glowcloud in PR review: - Uses existing plugin architecture instead of duplicating logic - Properly handles boolean vs number exclusiveMinimum/exclusiveMaximum - Exposes functions through fn.stringifyConstraintNumberRange and fn.jsonSchema202012.stringifyConstraintNumberRange

glowcloud

Great work on the refactor! Some additional changes are needed but the logic is sound. Please take a look at the new comments.

glowcloud · 2025-10-03T13:38:58Z

src/core/components/parameter-row.jsx

+            const isOAS31 = specSelectors.isOAS31 && specSelectors.isOAS31()
+            let numericConstraint = null
+
+            if (isOAS31 && fn.jsonSchema202012?.stringifyConstraintNumberRange) {


This can be avoided by overriding the function for OpenAPI 3.1 here, the same way it was done for these functions. The existing wrapper should identify if our specification is in version 3.1.x and use the correct function.

glowcloud · 2025-10-03T13:39:32Z

src/core/components/parameter-row.jsx

            : null
          }

+          {(() => {


Let's instead define the numericConstraint before the return, e.g.

const numericConstraint = fn.stringifyConstraintNumberRange(schema) return ( // ... {numericConstraint && <Markdown className="parameter__constraint" source={`<i>Constraints</i>: ${numericConstraint}`}/>} // ... )

glowcloud · 2025-10-03T13:40:57Z

src/core/plugins/json-schema-2020-12/fn.js

  return hasType(schemaType)
 }
+
+export { stringifyConstraintNumberRange }


We can instead simply export where the function is defined:

export const stringifyConstraintNumberRange = (schema) => {

glowcloud · 2025-10-03T13:46:52Z

src/core/plugins/json-schema-5/fn.js

+
+// For OpenAPI 2.0 and 3.0 (JSON Schema Draft 4/5)
+// where exclusiveMinimum and exclusiveMaximum are booleans
+export const stringifyConstraintNumberRange = (schema) => {


To avoid checking schema?.get every time, we could instead either transform schema to a plain object at the start with immutableToJS or have a helper function that will call this one after using immutableToJS. An example of the second option is here.

glowcloud · 2025-10-03T13:51:03Z

test/unit/core/plugins/constraint-functions.spec.js

+import { stringifyConstraintNumberRange as stringifyConstraintNumberRangeDraft5 } from "core/plugins/json-schema-5/fn"
+
+describe("stringifyConstraintNumberRange", () => {
+  describe("JSON Schema 2020-12 (OpenAPI 3.1)", () => {


Let's split the tests into separate files and put them under

test/unit/core/plugins/json-schema-5/fn

test/unit/core/plugins/json-schema-2020-12/fn

glowcloud · 2025-10-03T13:57:59Z

test/unit/components/parameter-row.jsx

+        isOAS3: () => isOAS3,
+        isSwagger2: () => !isOAS3,
+      },
+      fn: {


Would it be possible to provide the correct fn.stringifyConstraintNumberRange, based on the specification version, through here and test the display in these tests instead of parameter-constraints.spec.js?

SiddarthaKarri changed the title ~~Ft/10562 display parameter constraints~~ feat: display numeric constraints for path and query parameters Oct 2, 2025

SiddarthaKarri force-pushed the ft/10562-display-parameter-constraints branch from e7d5f21 to f22d157 Compare October 2, 2025 10:40

Merge branch 'master' into ft/10562-display-parameter-constraints

cd7ecc3

glowcloud added type: enhancement version: 5.x labels Oct 3, 2025

SiddarthaKarri and others added 2 commits October 3, 2025 18:02

Merge branch 'swagger-api:master' into ft/10562-display-parameter-con…

eae494f

…straints

glowcloud requested changes Oct 3, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: display numeric constraints for path and query parameters #10586

feat: display numeric constraints for path and query parameters #10586

Uh oh!

SiddarthaKarri commented Oct 2, 2025 •

edited

Loading

Uh oh!

glowcloud commented Oct 3, 2025

Uh oh!

glowcloud left a comment

Uh oh!

glowcloud Oct 3, 2025

Uh oh!

glowcloud Oct 3, 2025

Uh oh!

glowcloud Oct 3, 2025

Uh oh!

glowcloud Oct 3, 2025

Uh oh!

glowcloud Oct 3, 2025

Uh oh!

glowcloud Oct 3, 2025

Uh oh!

Uh oh!

feat: display numeric constraints for path and query parameters #10586

Are you sure you want to change the base?

feat: display numeric constraints for path and query parameters #10586

Uh oh!

Conversation

SiddarthaKarri commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Checklist

My PR contains...

My changes...

Documentation

Automated tests

Uh oh!

glowcloud commented Oct 3, 2025

Uh oh!

glowcloud left a comment

Choose a reason for hiding this comment

Uh oh!

glowcloud Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

glowcloud Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

glowcloud Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

glowcloud Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

glowcloud Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

glowcloud Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

SiddarthaKarri commented Oct 2, 2025 •

edited

Loading