example() on non-body parameters generates non-compliant Swagger 2.0 output

[22skyy]

Description

When using the example() attribute on query, path, header, or form parameters, swag generates an example field in the output YAML/JSON. However, the example field is not part of the Swagger 2.0 specification for Parameter Objects (non-body parameters).

This causes validation errors in downstream tools like OpenAPI Generator that strictly validate against the Swagger 2.0 specification.

Reproduction

Go code

// @Param categoryIds query string true "Category IDs (comma-separated)" example(1,2)

Generated Swagger YAML

parameters:
  - description: Category IDs (comma-separated)
    in: query
    name: categoryIds
    required: true
    type: string
    example: "1,2"  # ← This field is not valid in Swagger 2.0 for query parameters

Validation Error (OpenAPI Generator)

attribute paths.'/v1/endpoint'(get).[categoryIds].example is unexpected

Expected Behavior

Use x-example vendor extension for non-body parameters (Swagger 2.0 compliant):

parameters:
  - name: categoryIds
    in: query
    type: string
    x-example: "1,2"  # Vendor extensions are allowed

References

Swagger 2.0 Specification

The Swagger 2.0 Parameter Object specification defines the following fields for non-body parameters:

• name, in, description, required
• type, format, allowEmptyValue, items, collectionFormat
• default, maximum, exclusiveMaximum, minimum, exclusiveMinimum
• maxLength, minLength, pattern, maxItems, minItems
• uniqueItems, enum, multipleOf

Note: example is NOT listed. It is only available in the Schema Object (used for body parameters and definitions).

Vendor Extensions

According to Swagger vendor extensions documentation, the x-example extension can be used as a workaround for this limitation.

Environment

• swag version: v1.16.4
• Go version: 1.24.3
• Output format: Swagger 2.0 (default)

Related Issues

• How to declare example for string param? #445 - How to declare example for string param?
• swag generator shouldn't include type tag for refs if one exists already #625 - Similar non-compliance issue with type field (fixed in v1.6.5)

Proposed Solution

I'm happy to submit a PR to fix this. The proposed change:

For non-body parameters, use param.AddExtension("x-example", val) instead of param.Example = val in the setExample function.

This maintains backward compatibility for body parameters while producing spec-compliant output for other parameter types.