fix(swagger): add example field to path/form/header parameters#5497
Conversation
Fixes issue zeromicro#5496: the example= tag option in path, form and header struct tags was silently ignored when generating swagger JSON. SimpleSchema already has an Example field; wire it up via exampleValueFromOptions() the same way json body parameters do. - parameter.go: set SimpleSchema.Example for header, path, query and formData parameters - parameter_test.go: add TestParametersFromType_ExampleField to reproduce the issue - issue5496/: add reproduce example with .api and generated .json Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
kevwan
left a comment
kevwan
left a comment
There was a problem hiding this comment.
Review Summary
The fix is correct and minimal. The example= tag option was already handled for JSON body parameters via exampleValueFromOptions() — this PR consistently applies the same pattern to header, path, form/query, and formData parameters.
Observations:
Core fix (parameter.go) — LGTM. Four one-line additions, each mirroring the existing Default: field pattern directly above them. Low risk of regression.
Test (parameter_test.go) — TestParametersFromType_ExampleField covers both a path param with string example and a form/query param with integer example. The assert.EqualValues(t, int64(18), ...) works but note that the actual type returned by exampleValueFromOptions for an integer tag may vary across Go versions (currently int64). Using assert.EqualValues here is the right call since it avoids a hard type assertion.
Generated fixture (issue5496/issue5496.json) — The committed JSON file contains "x-date": "2026-03-19 22:52:34" which is a timestamp that will change with every goctl regeneration. This makes the file noisy in future diffs. Consider either:
- Removing
x-datefrom regression fixture files via a generator flag, or - Adding
issue5496/issue5496.jsonto.gitignoreand keeping only the.apifile as the canonical reproduction
This doesn't block the fix — the core code change is correct and ready to merge.
2 participants
Fixes issue #5496: the example= tag option in path, form and header struct tags was silently ignored when generating swagger JSON. SimpleSchema already has an Example field; wire it up via exampleValueFromOptions() the same way json body parameters do.