Skip to content

Feat/swagger omit - #67

Merged
fredbi merged 2 commits into
go-openapi:masterfrom
fredbi:feat/swagger-omit
Jul 30, 2026
Merged

fredbi merged 2 commits into
go-openapi:masterfrom
fredbi:feat/swagger-omit

Conversation

@fredbi

@fredbi fredbi commented Jul 30, 2026 •

Copy link
Copy Markdown
Member

Change type

Please select: 🆕 New feature or enhancement|🔧 Bug fix'|📃 Documentation update

Short description

Fixes

Full description

Checklist

  • I have signed all my commits with my name and email (see DCO. This does not require a PGP-signed commit
  • I have rebased and squashed my work, so only one commit remains
  • I have added tests to cover my changes.
  • I have properly enriched go doc comments in code.
  • I have properly documented any breaking change.

fredbi and others added 2 commits July 30, 2026 19:34
…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

codecov Bot commented Jul 30, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 85.23490% with 22 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.80%. Comparing base (37465c5) to head (c3e225a).
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
internal/builders/schema/omit.go 85.60% 13 Missing and 5 partials ⚠️
internal/builders/schema/allof.go 77.77% 1 Missing and 1 partial ⚠️
internal/parsers/grammar/annotations.go 50.00% 2 Missing ⚠️
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.
📢 Have feedback on the report? Share it here.

@fredbi
fredbi merged commit e5037f1 into go-openapi:master Jul 30, 2026
26 checks passed
@fredbi
fredbi deleted the feat/swagger-omit branch July 30, 2026 17:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

⌂ 换网址