Repository navigation
Feat/swagger omit - #67
Merged
Merged
Conversation
…onflicts
Promoting an embed can produce a schema its author never meant, and codescan
must not guess which one they meant:
- an outer field re-declared to decorate a promoted one (add `readOnly`, a
description, a validation) marshals as ONE field in Go, but composes into
`allOf` as two — the same property in both members;
- an outer field re-declared with a different type composes into `{type:
integer}` AND `{type: string}` for one property: a schema nothing can
satisfy;
- a shared domain type embedded in a request body carries every field it has,
including the ones the endpoint does not accept (go-swagger#1992).
The root cause of the first two is that inlining RESOLVES an override (Go's
depth rule picks the winner) while `allOf` ACCUMULATES: members conjoin, and a
conjunction can only narrow, never replace. An override that replaces is
therefore not expressible as composition, and tidying the members cannot fix it.
The third is not a defect at all — the type really does carry those fields.
Rather than infer intent (there are many ways to write a Go type whose
composition cannot be expressed, and the scanner's job is to document the code),
add an explicit in-band escape hatch:
// swagger:omit <name>[,<name>…]
Names are Go field names, never JSON aliases. Two placements: on the embed,
where targets are plain field names of that type, and on the declaration, where
a dotted path names the embed chain (`Base.ID`) and a bare name resolves against
the promoted set. Embeds only — every path segment but the last must name an
embedded field, since `omit` removes promoted content, the one thing the
enclosing schema owns; reaching through a regular field would edit either
another type's inlined copy or a `$ref`'d definition.
It is a PRE-filter, not a post-hoc delete: "do not promote this field when
walking the embed". One rule then covers both renderings — inlined, an outer
re-declaration wins as it already did (so omitting its promoted twin is
correctly a no-op); composed, the base member is built without the field, which
removes the duplicate and the unsatisfiable pair. Filtering before names exist
also makes the annotation indifferent to json tags and to NameFromTags.
Targets resolve against the TYPE, not the walk: once, at the annotation site,
via types.LookupFieldOrMethod — Go's own promoted-field lookup, so depth and
ambiguity rules come for free. The scope carries the resulting *types.Var and
the filter is pointer identity. Hence no "what was actually omitted"
bookkeeping, no confusion between same-named fields at different depths, and no
diagnostic for a target already excluded for another reason.
Three Hints, never blocking:
- scan.omit-unresolved — the target names no field of the embedded type.
`swagger:omit` is the only construct whose output depends on a hand-written
name the compiler never checks (everything else is derived from types), so
an unresolved target must be reported or a rename upstream would silently
put the field back.
- scan.omit-behind-ref — the embed is composed as a `$ref` (an annotated
model), where OAS2 cannot subtract a property; the omission is dropped
rather than silently forking the referenced definition.
- scan.shadowed-embed-field — a field re-declared with `json:"-"` carries the
Go name of a promoted one. encoding/json ignores a `-` field ENTIRELY, so it
never shadows anything and Go keeps marshalling the embedded field; the Hint
points at swagger:omit, which drops it for real. The existing (unfaithful)
eviction is left in place — removing it changes output and is a separate
decision.
Two fixtures: enhancements/swagger-omit (both placements, an embed chain, both
renderings, all three Hints, and the go-swagger#1992 body shape verbatim —
reduced to exactly the field the author kept), and
enhancements/default-allof-embeds-override, which locks the same overrides
WITHOUT the annotation as the documented limit of composition.
The parameters builder needs no change: a `swagger:parameters` body struct is
built through the schema builder, so the embed walk is shared.
Contributes to go-swagger/go-swagger#1992.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Reference page for the new annotation, plus the two index entries and a section in the allOf how-to explaining why the escape hatch exists. The reference page covers both placements (on the embed, where targets are plain field names of that type; on the declaration, where a dotted path names the embed chain), the embeds-only rule and why it is not a restriction worth lifting (`omit` removes promoted content, the only thing the enclosing schema owns), the EBNF, and the three Hints. It also warns about the trap the annotation replaces: re-declaring a promoted field with `json:"-"` looks like it hides it, but encoding/json ignores a `-` field entirely, so it never shadows the promoted one and Go keeps marshalling it. `shaping-the-output/names-and-refs/composing-embeds-with-allof` gains a "When an override cannot be composed" section: inlining RESOLVES an override (Go's depth rule picks a winner) while allOf ACCUMULATES (members conjoin, and a conjunction can only narrow, never replace), so a re-declaration that replaces has no faithful composed form — duplicated for a decoration, unsatisfiable for a retype. That is the limit `swagger:omit` lets the author resolve, and stating it where `DefaultAllOfForEmbeds` is documented is where a reader will hit it. New witness docs/examples/concepts/omit backs the page with the go-swagger#1992 shape: the request body embeds the shared type minus the server-assigned fields, while the type's own definition — which the response $refs — still documents all of them, showing the omission is local to the body that asked for it and never a mutation of the shared definition. Verified with a full hugo build: 106 pages, no warnings, the example shortcodes resolve their files, and the new page is linked from both indexes and the how-to. Contributes to go-swagger/go-swagger#1992. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## master #67 +/- ##
==========================================
+ Coverage 81.73% 81.80% +0.07%
==========================================
Files 85 86 +1
Lines 8645 8789 +144
==========================================
+ Hits 7066 7190 +124
- Misses 1153 1168 +15
- Partials 426 431 +5 ☔ View full report in Codecov by Harness. |
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
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
Fixes
Full description
Checklist