Skip to content

Commit 23ffe2a

Browse files
fredbiclaude
andcommitted
fix(responses): annotation gates first-class alias identity at use sites
Mirrors the parameters-builder rule and the schema-builder use-site rule, applied to the responses layer. Two rules land: 1. Top-level alias annotated `swagger:response` is transparent re: model creation. Neither the alias decl nor any chain link of its backing struct surfaces as a `definitions` entry — the fields of the unaliased target become the response's body and headers. The `swagger:response` annotation declares a response, not a model. This commit also fixes two pre-existing bugs surfaced by the calibration fixture: - Default mode crashed on top-level response aliases with "anonymous types are currently not supported for responses" — the old code walked `tpe.Unalias().Underlying()` and handed a *types.Struct to buildFromType, which has no case for anonymous structs. - RefAliases mode produced an EMPTY body schema on the top-level response — the old MakeRef branch created a throwaway typable that never connected to the response object. Routing through `buildFromType(tpe.Rhs())` dispatches to buildNamedType -> buildFromStruct for the backing Named struct, which is the same path a directly-declared `swagger:response` struct takes. Both bugs vanish. 2. Body field aliases follow the same gate as parameters and schema: - annotated alias → `$ref` preserves the alias name; the alias gets its own definition via MakeRef's AppendPostDecl side effect; - unannotated alias → dissolve via `types.Unalias` to the unaliased target (full chain collapse in one step), no `definitions` entry for the alias. TransparentAliases still supersedes the annotation gate at use sites. Non-body fields are SimpleSchema targets and cannot carry `$ref`; they always expand to the unaliased target regardless of annotation. Adds the `alias-responses-calibration` fixture exercising all three reach contexts under all three modes. The coverage tests pin the contract per mode with both inline assertions and goldens. Cross-fixture cleanup is substantial: the `enhancements_alias_response_ref.json` golden now carries real `schema: $ref: Envelope` on both top-level response aliases (previously empty schemas), and the `exportedResponse` / `AliasedTopResponse` / `EnvelopeAlias` chain leaks vanish across `enhancements_alias_response_shapes_ref.json`, `enhancements_alias_findmodel_witness.json`, and `enhancements_alias_ref.json`. Annotated companions land alongside the unannotated witnesses across `alias-response-shapes`, `alias-expand` (response side), and `alias-findmodel-witness` (both parameter and response sides) — each post-fix golden now carries both halves of the contract on the same canvas: the unannotated path that dissolves and the annotated path that preserves the alias name via `swagger:model`. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
1 parent 40978ce commit 23ffe2a

20 files changed

Lines changed: 1096 additions & 86 deletions

‎fixtures/enhancements/alias-expand/api.go‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,29 @@ type AliasedResponse struct {
9696
Body EnvelopeAlias2 `json:"body"`
9797
}
9898

99+
// EnvelopeAliasModeled is the annotated counterpart of
100+
// EnvelopeAlias. With `swagger:model` the alias opts in as a
101+
// first-class spec entity; R8 then preserves the alias name at
102+
// body field sites in `swagger:response` structs.
103+
//
104+
// swagger:model EnvelopeAliasModeled
105+
type EnvelopeAliasModeled = ResponseEnvelope
106+
107+
// AliasedModeledResponse is the bidirectional sibling of
108+
// AliasedResponse: same shape, but its Body field uses the
109+
// ANNOTATED alias `EnvelopeAliasModeled`. Under R8 the body
110+
// schema's `$ref` preserves `EnvelopeAliasModeled` (alongside
111+
// the alias's own definition), while AliasedResponse dissolves
112+
// to `$ref: ResponseEnvelope`. Both halves on one canvas.
113+
//
114+
// swagger:response aliasedModeledResponse
115+
type AliasedModeledResponse struct {
116+
// Body is an annotated alias.
117+
//
118+
// in: body
119+
Body EnvelopeAliasModeled `json:"body"`
120+
}
121+
99122
// exportedParams is the backing struct for an aliased swagger:parameters.
100123
type exportedParams struct {
101124
// in: query

‎fixtures/enhancements/alias-findmodel-witness/api.go‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,3 +51,36 @@ type WitnessResponse struct {
5151
// in: body
5252
Body AliasOfPlain `json:"body"`
5353
}
54+
55+
// AliasOfPlainModeled is the ANNOTATED counterpart of AliasOfPlain.
56+
// Same underlying Named target (PlainTarget — still unannotated by
57+
// design) but the alias itself carries `swagger:model`. Under
58+
// R6 / R7 / R8 the annotation preserves the alias name at every
59+
// use site; without it the alias dissolves to PlainTarget. The
60+
// witness pair below pins both halves on one canvas.
61+
//
62+
// swagger:model AliasOfPlainModeled
63+
type AliasOfPlainModeled = PlainTarget
64+
65+
// WitnessParamsModeled is the bidirectional sibling of WitnessParams.
66+
// Same shape, but its Body field uses the ANNOTATED alias
67+
// `AliasOfPlainModeled`. R7 preserves the alias name in the body
68+
// parameter's $ref while WitnessParams.Body dissolves to PlainTarget.
69+
//
70+
// swagger:parameters witnessModeledRequest
71+
type WitnessParamsModeled struct {
72+
// in: body
73+
// required: true
74+
Body AliasOfPlainModeled `json:"body"`
75+
}
76+
77+
// WitnessResponseModeled mirrors WitnessParamsModeled on the
78+
// response side — R8 preserves the annotated alias's identity at
79+
// the body response schema, recovering the pre-R8 alias-name
80+
// $ref behaviour for opted-in users.
81+
//
82+
// swagger:response witnessModeledResponse
83+
type WitnessResponseModeled struct {
84+
// in: body
85+
Body AliasOfPlainModeled `json:"body"`
86+
}

‎fixtures/enhancements/alias-response-shapes/api.go‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,3 +70,26 @@ type HeaderAliasedStructResponse struct {
7070
// in: header
7171
Detail EnvelopeAlias `json:"X-Detail"`
7272
}
73+
74+
// EnvelopeAliasModeled is the annotated counterpart of
75+
// EnvelopeAlias. R8 makes the annotation the gate for first-class
76+
// alias identity at body field sites; this decl exists so the
77+
// bidirectional contract is visible on the same canvas as the
78+
// unannotated witnesses above.
79+
//
80+
// swagger:model EnvelopeAliasModeled
81+
type EnvelopeAliasModeled = Envelope
82+
83+
// BodyAliasModeledResponse — body field uses the ANNOTATED alias
84+
// EnvelopeAliasModeled. Under R8 the body schema's `$ref`
85+
// preserves the alias name (`$ref: EnvelopeAliasModeled`),
86+
// recovering the pre-R8 alias-name $ref behaviour for users who
87+
// explicitly opt in via `swagger:model`. The unannotated
88+
// counterpart (BodyAliasResponse above) dissolves to
89+
// `$ref: Envelope`.
90+
//
91+
// swagger:response bodyAliasModeledResponse
92+
type BodyAliasModeledResponse struct {
93+
// in: body
94+
Body EnvelopeAliasModeled `json:"body"`
95+
}
Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
package alias_responses_calibration
5+
6+
// AliasedTopHandler binds the top-level aliased response to an
7+
// operation so the response shape is observable on a path.
8+
//
9+
// swagger:route GET /aliased-top calibration aliasedTopOp
10+
//
11+
// Responses:
12+
//
13+
// 200: aliasedTopResponse
14+
func AliasedTopHandler() {}
15+
16+
// DirectHandler binds the control response to an operation.
17+
//
18+
// swagger:route POST /direct calibration directOp
19+
//
20+
// Responses:
21+
//
22+
// 200: directResponse
23+
func DirectHandler() {}
24+
25+
// BodyAliasPlainHandler binds the unannotated body-alias response.
26+
//
27+
// swagger:route GET /body-alias-plain calibration bodyAliasPlainOp
28+
//
29+
// Responses:
30+
//
31+
// 200: bodyAliasPlainResponse
32+
func BodyAliasPlainHandler() {}
33+
34+
// BodyAliasModeledHandler binds the annotated body-alias response.
35+
//
36+
// swagger:route GET /body-alias-modeled calibration bodyAliasModeledOp
37+
//
38+
// Responses:
39+
//
40+
// 200: bodyAliasModeledResponse
41+
func BodyAliasModeledHandler() {}
42+
43+
// BodyAliasChainHandler binds the 2-link chain body-alias response.
44+
//
45+
// swagger:route GET /body-alias-chain calibration bodyAliasChainOp
46+
//
47+
// Responses:
48+
//
49+
// 200: bodyAliasChainResponse
50+
func BodyAliasChainHandler() {}
Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
// Package alias_responses_calibration is the cycle-5 calibration
5+
// fixture for the W3 alias workshop — the responses-builder
6+
// analogue of cycle-4 (alias-parameters-calibration).
7+
//
8+
// The fixture surfaces the responses-builder's current behaviour
9+
// for the three reach contexts the cycle-5 workshop has to cover:
10+
//
11+
// 1. Top-level alias annotated `swagger:response` —
12+
// AliasedTopResponse = internalResponse. The existing
13+
// alias-response/ fixture documents that the Default mode
14+
// crashes on this path ("anonymous types are currently not
15+
// supported for responses"); R8 should fix that as a side
16+
// effect of routing through the alias's RHS.
17+
// 2. Body field typed as an alias, both annotated and unannotated
18+
// — DirectResponse.BodyAliasPlain / .BodyAliasModeled.
19+
// 3. Non-body (header) field typed as an alias — DirectResponse
20+
// header fields.
21+
//
22+
// `DirectResponse` carries the control case (BodyDirect typed as
23+
// the raw Envelope model) alongside the alias variants so the
24+
// comparison is on one canvas.
25+
//
26+
// Two real `swagger:route` handlers bind the responses to
27+
// operations so the response shapes are visible in the captured
28+
// spec under the operations' `responses` block (and any
29+
// auto-discovered top-level entries under the spec's `responses`
30+
// block too).
31+
//
32+
// See `.claude/plans/workshops/alias-responses.md` §4 for the R8
33+
// rule candidate and `.claude/plans/workshops/alias-ledger.md`
34+
// cycle 5 for the running judgment record.
35+
package alias_responses_calibration
36+
37+
// Envelope is the canonical response body model.
38+
//
39+
// swagger:model Envelope
40+
type Envelope struct {
41+
// required: true
42+
ID int64 `json:"id"`
43+
44+
Name string `json:"name"`
45+
}
46+
47+
// HeaderID is a named string backing the non-body (header) alias
48+
// witnesses. SimpleSchema targets can't carry $ref, so R8 clause 3
49+
// always expands non-body aliases regardless of annotation.
50+
type HeaderID string
51+
52+
// EnvelopeAlias is an UNANNOTATED alias of Envelope. Under R8 the
53+
// body field reference must dissolve to `$ref: Envelope` (not
54+
// `$ref: EnvelopeAlias`), and the alias must not produce its own
55+
// `definitions` entry.
56+
type EnvelopeAlias = Envelope
57+
58+
// EnvelopeAliasModeled is the ANNOTATED counterpart of
59+
// EnvelopeAlias. `swagger:model` opts the alias in as a
60+
// first-class spec entity — body field sites preserve
61+
// `$ref: EnvelopeAliasModeled` and the alias gets its own
62+
// definition.
63+
//
64+
// swagger:model EnvelopeAliasModeled
65+
type EnvelopeAliasModeled = Envelope
66+
67+
// EnvelopeAlias2 is a 2-link unannotated chain. Both links
68+
// dissolve under R8 → body fields land on `$ref: Envelope`.
69+
type EnvelopeAlias2 = EnvelopeAlias
70+
71+
// HeaderIDAlias is an unannotated alias of HeaderID. Non-body
72+
// SimpleSchema use sites can't carry $ref regardless of annotation;
73+
// the witness mainly asserts the alias does not produce a dangling
74+
// definition.
75+
type HeaderIDAlias = HeaderID
76+
77+
// internalResponse is the unexported backing struct for the
78+
// top-level aliased response below. Q12 witness — pre-R8 captures
79+
// surface this struct as a `definitions` entry under non-Transparent
80+
// modes despite carrying no `swagger:model` annotation.
81+
type internalResponse struct {
82+
// Body is the response body for the aliased top-level response.
83+
//
84+
// in: body
85+
Body Envelope `json:"body"`
86+
87+
// XSession is a header on the aliased top-level response.
88+
//
89+
// in: header
90+
XSession HeaderID `json:"X-Session"`
91+
}
92+
93+
// AliasedTopResponse is a top-level alias annotated
94+
// `swagger:response`. R8 clause 1 says neither this alias nor its
95+
// backing struct should surface in `definitions` — the response's
96+
// body / headers come from the fields of the unaliased target.
97+
//
98+
// swagger:response aliasedTopResponse
99+
type AliasedTopResponse = internalResponse
100+
101+
// DirectResponse is the control response: declared directly (not
102+
// via an alias), holding body and non-body fields typed as the
103+
// alias variants above so every reach context is visible inside
104+
// one response.
105+
//
106+
// swagger:response directResponse
107+
type DirectResponse struct {
108+
// BodyDirect — body typed as the raw Envelope model (control
109+
// case, R6/R7/R8-independent).
110+
//
111+
// in: body
112+
BodyDirect Envelope `json:"bodyDirect"`
113+
114+
// XHeaderPlain — header typed as the UNANNOTATED alias
115+
// HeaderIDAlias. SimpleSchema target — the alias must expand
116+
// to its primitive type inline regardless of mode, and
117+
// HeaderIDAlias must not appear in `definitions`.
118+
//
119+
// in: header
120+
XHeaderPlain HeaderIDAlias `json:"X-Header-Plain"`
121+
}
122+
123+
// BodyAliasPlainResponse — body response typed as the UNANNOTATED
124+
// alias EnvelopeAlias. Under R8 the body schema's $ref dissolves
125+
// to Envelope.
126+
//
127+
// swagger:response bodyAliasPlainResponse
128+
type BodyAliasPlainResponse struct {
129+
// in: body
130+
Body EnvelopeAlias `json:"body"`
131+
}
132+
133+
// BodyAliasModeledResponse — body response typed as the
134+
// ANNOTATED alias EnvelopeAliasModeled. Under R8 the body
135+
// schema's $ref preserves EnvelopeAliasModeled (and the alias
136+
// surfaces as its own definition).
137+
//
138+
// swagger:response bodyAliasModeledResponse
139+
type BodyAliasModeledResponse struct {
140+
// in: body
141+
Body EnvelopeAliasModeled `json:"body"`
142+
}
143+
144+
// BodyAliasChainResponse — body response typed as the 2-link
145+
// unannotated chain EnvelopeAlias2. Both layers dissolve to
146+
// Envelope.
147+
//
148+
// swagger:response bodyAliasChainResponse
149+
type BodyAliasChainResponse struct {
150+
// in: body
151+
Body EnvelopeAlias2 `json:"body"`
152+
}

‎fixtures/integration/golden/enhancements_alias_expand.json‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,31 @@
22
"swagger": "2.0",
33
"paths": {},
44
"definitions": {
5+
"EnvelopeAliasModeled": {
6+
"description": "EnvelopeAliasModeled is the annotated counterpart of\nEnvelopeAlias. With `swagger:model` the alias opts in as a\nfirst-class spec entity; R8 then preserves the alias name at\nbody field sites in `swagger:response` structs.",
7+
"type": "object",
8+
"properties": {
9+
"payload": {
10+
"type": "object",
11+
"required": [
12+
"id"
13+
],
14+
"properties": {
15+
"id": {
16+
"type": "integer",
17+
"format": "int64",
18+
"x-go-name": "ID"
19+
},
20+
"name": {
21+
"type": "string",
22+
"x-go-name": "Name"
23+
}
24+
},
25+
"x-go-name": "Payload"
26+
}
27+
},
28+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/alias-expand"
29+
},
530
"Payload": {
631
"type": "object",
732
"title": "Payload is the canonical struct referenced by aliases.",
@@ -63,6 +88,12 @@
6388
}
6489
},
6590
"responses": {
91+
"aliasedModeledResponse": {
92+
"description": "AliasedModeledResponse is the bidirectional sibling of\nAliasedResponse: same shape, but its Body field uses the\nANNOTATED alias `EnvelopeAliasModeled`. Under R8 the body\nschema's `$ref` preserves `EnvelopeAliasModeled` (alongside\nthe alias's own definition), while AliasedResponse dissolves\nto `$ref: ResponseEnvelope`. Both halves on one canvas.",
93+
"schema": {
94+
"$ref": "#/definitions/EnvelopeAliasModeled"
95+
}
96+
},
6697
"aliasedResponse": {
6798
"description": "AliasedResponse has a body field whose type is an alias chain.",
6899
"schema": {

‎fixtures/integration/golden/enhancements_alias_findmodel_witness.json‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,9 @@
22
"swagger": "2.0",
33
"paths": {},
44
"definitions": {
5-
"AliasOfPlain": {
6-
"title": "AliasOfPlain is an alias pointing at the unannotated target.",
5+
"AliasOfPlainModeled": {
6+
"description": "Same underlying Named target (PlainTarget — still unannotated by\ndesign) but the alias itself carries `swagger:model`. Under\nR6 / R7 / R8 the annotation preserves the alias name at every\nuse site; without it the alias dissolves to PlainTarget. The\nwitness pair below pins both halves on one canvas.",
7+
"title": "AliasOfPlainModeled is the ANNOTATED counterpart of AliasOfPlain.",
78
"$ref": "#/definitions/PlainTarget"
89
},
910
"PlainTarget": {
@@ -28,10 +29,16 @@
2829
}
2930
},
3031
"responses": {
32+
"witnessModeledResponse": {
33+
"description": "WitnessResponseModeled mirrors WitnessParamsModeled on the\nresponse side — R8 preserves the annotated alias's identity at\nthe body response schema, recovering the pre-R8 alias-name\n$ref behaviour for opted-in users.",
34+
"schema": {
35+
"$ref": "#/definitions/AliasOfPlainModeled"
36+
}
37+
},
3138
"witnessResponse": {
3239
"description": "WitnessResponse has a response body whose Go type is the same\nalias — mirror witness on the response builder's\nbuildFieldAlias path.",
3340
"schema": {
34-
"$ref": "#/definitions/AliasOfPlain"
41+
"$ref": "#/definitions/PlainTarget"
3542
}
3643
}
3744
}

0 commit comments

Comments
 (0)
⌂ 换网址