Fix/3412 enum negative - #76
Merged
Merged
Conversation
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Member
Author
|
Supersedes #75 |
Both the members of a swagger:enum and the type of the schema carrying them were
derived from the literal syntax of the const block. Neither survives that reading
intact: a constant's right-hand side is only incidentally a literal, and a value
carries no trace of the width it was declared with.
Members:
- a signed constant (-1) is a unary expression, not a literal, and was skipped,
so an enum straddling zero lost half its members;
- the non-decimal forms (0x2a, 0b101010, 0o52) and digit separators failed a
base-10 parse and reached the spec as a null member; a value above MaxInt64,
legal for a uint64 enum, was dropped;
- iota, constant expressions, references to earlier members, rune literals,
true/false and the raw string form were invisible, since their value is not in
their syntax and inside an iota block only the first spec carries a type at
all. Members now come from the type-checker, which evaluated them exactly, and
membership is decided per name from the constant's own type — the package
included, so a same-named imported type is not swallowed.
The literal reader survives as the fallback for a package that only partially
type-checks, where an annotated enum should still contribute what can be read.
Typing:
- type and format come from the declared Go type rather than from the first
value's Go representation: an int8 enum is {integer, int8}, a float32 one
{number, float}. Every width used to collapse, and the declaration order of
the const block decided the type — a float enum whose first member was written
`= 0` emitted {type: integer} carrying fractional members;
- each member is normalised to that type, and one that cannot be represented in
it is reported and dropped rather than written against the schema's own type;
- a type declared over another named type (type Kind strfmt.UUID) keeps the
format of the type it is written over, which Underlying() does not carry.
An enum built from iota, booleans or expressions used to emit nothing plus a "no
matching const values found" warning; it now emits its values.
A rune or byte enum is among those newly emitted, and it emits an integer enum:
`const LetterA Letter = 'a'` becomes {integer, int32} with the member 97. That
is likely not what its author pictured, and it is still the only faithful
answer — a scalar rune is an int32 on the wire, and encoding/json refuses to
unmarshal "a" into that field. Declaring the type over string is what changes
the wire, and with it the schema.
No existing golden changes: the corpus held no enum that was negative, sized,
iota-based or strfmt-backed, which is why none of this was visible.
Refers to go-swagger/go-swagger#3412.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
The enum section under "Model definitions" covered a string const block and little else. Enums get their own page, next to it in the tutorial order: what the scanner collects (any constant expression, iota included), what decides the emitted type and format, the inline form parameters and headers take, and the two shapes that do not work — a rune or byte enum, which emits code points because that is what those types are on the wire, and an alias to a basic type, which the type-checker erases before there is anything left to collect. A new docs/examples/concepts/enums package backs the panes, one region per rule, its fragments regenerated as goldens like the other tutorials. Model definitions keeps its introductory pane and points at the new page; the annotation index and the swagger:enum reference follow. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
fredbi
force-pushed
the
fix/3412-enum-negative
branch
from
August 1, 2026 12:10
a915317 to
7afe0e3
Compare
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Change type
Please select: 🆕 New feature or enhancement|🔧 Bug fix'|📃 Documentation update
Short description
This PR reworks how enums are identified and associated with a swagger type.
This allows for supported a wider range of valid go const constructs, including negative values, hex/octal literals,
redefined basic types, possibly bearing the "swagger:strfmt" annotation.
Adds a full tutorial to present the enhanced enum feature.
Fixes
Full description
Checklist