fix: use x-example for non-body parameters in Swagger 2.0

[22skyy]

Summary

Fix non-compliant Swagger 2.0 output when using example() attribute on non-body parameters.

Problem

The example field is not part of the Swagger 2.0 Parameter Object specification for query/path/header/form parameters. It is only valid in Schema Object (used for body parameters).

This causes validation errors in downstream tools like OpenAPI Generator:

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

Solution

For non-body parameters, use the x-example vendor extension instead of example. This is the recommended workaround for Swagger 2.0.

Body parameters continue to use example as before, since they use Schema Object where example is valid.

Before

parameters:
  - name: categoryIds
    in: query
    example: "1,2"  # Not valid in Swagger 2.0

After

parameters:
  - name: categoryIds
    in: query
    x-example: "1,2"  # Valid vendor extension

Changes

• operation.go: Modified setExample() to use vendor extension for non-body parameters
• operation_test.go: Updated existing tests and added new test cases

Breaking Changes

Non-body parameters will now output x-example instead of example. This is technically a breaking change for tools that specifically look for example on non-body parameters, but it fixes spec compliance.

References

• https://swagger.io/specification/v2/#parameter-object
• https://swagger.io/docs/specification/v2_0/swagger-extensions/
• Fixes example() on non-body parameters generates non-compliant Swagger 2.0 output #2137