Contradiction between Swagger Documentation and practical use of 'default' in query parameters

[fabio-resende]

According to the official Swagger/OpenAPI documentation:

There are two common mistakes when using the default keyword:

• Using default with required parameters does not make sense – if a value is required, the client must always send it, and the default value is never used.
• Using default to specify a sample value. This is not intended use of default and can lead to unexpected behavior in some Swagger tools. Use the example or examples keyword for this purpose instead

However, in practice, when we add default to a required parameter, Swagger tools (UI and code generators) use that value to:

• Pre-fill the field in Try it out.
• Generate the URL with the parameter included in Request Samples (e.g., curl). - Which is contradicting since you don't have to pass a default value.
• Make testing easier without requiring manual input.

On the other hand, if we do not set a default, even for required parameters, the generated URL in samples omits the parameter, and the Try it out field remains empty, which often causes errors during testing.
This creates a contradiction:

• Specification: default is intended for optional parameters, used by the server when the client does not send a value.
• Tools: default is treated as a way to auto-fill Try it Out and Request Samples, generating confusing URLs that dont need those parameters.

Questions:

Is there an official recommendation to handle this inconsistency?
Are there plans for Swagger UI to use example (or examples) for auto-filling required fields instead of relying on default?
What is considered best practice to maintain semantic correctness while providing a good user experience?

Thanks!

[handrews]

official Swagger/OpenAPI documentation

The only official OpenAPI documentation is spec.openapis.com and learn.openapis.com. We are not responsible for Swagger, Swagger UI, or the contents of the Swagger web site.

The spec defines what is correct. Anything else a tool does is a problem to take up with the tooling vendor.