Skip to content

Commit dc05fb6

Browse files
fredbiclaude
andcommitted
docs: doc-site coverage for shared parameters & responses
Document the shared-parameters feature (go-swagger#2632) landed on this branch, which shipped with fixtures and integration tests but no doc-site coverage. New tutorial (tutorials/sharing-parameters-and-responses.md, weight 25, auto-listed between Routes and Validations): - swagger:parameters * / * <opid> — register fields at #/parameters and $ref them into operations; the standalone `<opid> <name>` marker on a func as the scaling channel. - swagger:parameters /path — inline fields into a path-item (exact path, no hierarchy; co-present with operation-level params). - swagger:response * — register a shared response at #/responses. - The keep-first / dangling-ref / dedup semantics with their six scan.* diagnostic codes. Backed by a new test-covered witness (docs/examples/concepts/sharedparams) mirroring the integration-test ground truth: every JSON pane is a golden a test regenerates (UPDATE_GOLDEN=1 go test ./...). Reference touches (kept light): - annotations.md: a "Shared & path-item targets" note on swagger:parameters and the `*` synonym on swagger:response, both linking the new tutorial. - routes-and-operations.md: forward link to the new tutorial. * contributes go-swagger/go-swagger#2632 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
1 parent c561198 commit dc05fb6

10 files changed

Lines changed: 528 additions & 1 deletion

File tree

‎docs/doc-site/maintainers/annotations.md‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -682,6 +682,22 @@ packages** and matched to operations by operation ID — so a shared
682682
parameter set can live in its own package, as long as that package is in
683683
the scan set.
684684

685+
**Shared & path-item targets.** The first argument need not be an
686+
operation ID. A `*` wildcard or a `/path` switches the annotation to the
687+
spec-level **shared namespace**:
688+
689+
- `swagger:parameters *` registers the struct's fields at the spec top
690+
level (`#/parameters/{name}`) for reuse; `swagger:parameters * <opid>…`
691+
also `$ref`s them into the listed operations.
692+
- `swagger:parameters /path` inlines the fields into that **exact**
693+
path-item (OAS2 has no path hierarchy).
694+
- A standalone `swagger:parameters <opid> <name>…` (or `/path <name>…`)
695+
marker on a **function** `$ref`s an already-registered shared parameter
696+
into that operation / path-item.
697+
698+
See [Sharing parameters & responses]({{% relref "/tutorials/sharing-parameters-and-responses" %}})
699+
for the walkthrough and the keep-first / dangling-ref diagnostics.
700+
685701
**Sample.**
686702

687703
```go
@@ -755,7 +771,10 @@ intentional, not a missing type.
755771
**Where it goes.** On a struct declaration.
756772

757773
**Argument shape.** Optional IDENT — the published response name.
758-
Default: the Go type's name.
774+
Default: the Go type's name. A `*` wildcard (`swagger:response *`) is a
775+
synonym for the bare form that explicitly marks the response as a
776+
**shared** one, registered at `#/responses/{name}` for operations to
777+
`$ref` by name — see [Sharing parameters & responses]({{% relref "/tutorials/sharing-parameters-and-responses" %}}).
759778

760779
**Sample.**
761780

‎docs/doc-site/tutorials/routes-and-operations.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,8 @@ reads better on a single-line doc comment:
113113

114114
## What's next
115115

116+
- [Sharing parameters & responses]({{% relref "/tutorials/sharing-parameters-and-responses" %}})
117+
— declare a header or error response once and `$ref` it from many operations.
116118
- [Validations]({{% relref "/tutorials/validations" %}}) — constrain parameter
117119
and field values.
118120
- [Model definitions]({{% relref "/tutorials/model-definitions" %}}) — the
Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
title: Sharing parameters & responses
3+
weight: 25
4+
description: |
5+
Declare a parameter or response once and reuse it across operations through
6+
the spec-level shared namespace, with the wildcard swagger:parameters and
7+
swagger:response forms.
8+
---
9+
10+
When the same header, query parameter or error response appears on many
11+
operations, you don't have to repeat it. codescan can publish a parameter or
12+
response **once** into the spec's top-level `parameters` / `responses` maps, then
13+
reference it from each operation as a `$ref`. This is the OpenAPI 2.0 shared
14+
namespace (`#/parameters/{name}`, `#/responses/{name}`).
15+
16+
Each pane below pairs the annotated Go (left) with the exact fragment the scanner
17+
emits (right), from the test-covered
18+
[`docs/examples/concepts/sharedparams`](https://github.com/go-openapi/codescan/tree/master/docs/examples/concepts/sharedparams)
19+
package. For the per-operation basics this builds on — the plain
20+
`swagger:parameters <operationID>` and `swagger:response <name>` forms — see
21+
[Routes & operations]({{% relref "/tutorials/routes-and-operations" %}}).
22+
23+
## Declaring a shared parameter
24+
25+
`swagger:parameters *` declares a struct whose fields are registered at the spec
26+
top level, `#/parameters/{name}`, keyed by each parameter's resolved name. The
27+
bare `*` is **register-only**: it publishes the parameter but does not, by
28+
itself, attach it to any operation.
29+
30+
The convenience form `swagger:parameters * <operationID>…` does both at once — it
31+
registers the parameter **and** `$ref`s it into the listed operations, which is
32+
handy for a small spec.
33+
34+
{{< code file="concepts/sharedparams/sharedparams.go" lang="go" region="shared" >}}
35+
36+
Both structs land in the top-level `parameters` map, each keyed by its parameter
37+
name (the `json:` tag, or a `name:` / `swagger:name` override):
38+
39+
{{< code file="concepts/sharedparams/testdata/parameters.json" lang="json" >}}
40+
41+
## Referencing a shared parameter
42+
43+
Once a parameter is registered, an operation can pull it in by name. There are
44+
two reference channels:
45+
46+
- **`swagger:parameters * <operationID>`** on the declaring struct — the
47+
convenience form above. `AuthHeader` uses it to inject `X-API-Key` into
48+
`createPet`.
49+
- **`swagger:parameters <operationID> <name>…`** as a standalone marker on the
50+
operation's function — the *scaling* channel: the shared struct need not
51+
enumerate every operation that wants the parameter; instead each operation
52+
opts in next to its own `swagger:route`.
53+
54+
{{< code file="concepts/sharedparams/sharedparams.go" lang="go" region="routes" >}}
55+
56+
`listPets` opts in through the standalone marker, so its only parameter is a
57+
`$ref` to the shared `X-Request-ID`:
58+
59+
{{< code file="concepts/sharedparams/testdata/listpets.json" lang="json" >}}
60+
61+
`createPet` receives the `$ref`'d `X-API-Key` (from `* createPet`) **alongside**
62+
its own inlined body parameter — references and inline parameters coexist:
63+
64+
{{< code file="concepts/sharedparams/testdata/createpet.json" lang="json" >}}
65+
66+
## Path-item parameters
67+
68+
A parameter can also attach to a whole **path** rather than a single operation.
69+
`swagger:parameters /path` inlines a struct's fields into the path-item's
70+
`parameters` array, so every operation under that path inherits them.
71+
72+
{{< code file="concepts/sharedparams/sharedparams.go" lang="go" region="pathitem" >}}
73+
74+
`X-Tenant` now rides the `/pets/{id}` path-item; `getPet` inherits it without
75+
declaring a header of its own:
76+
77+
{{< code file="concepts/sharedparams/testdata/pathitem.json" lang="json" >}}
78+
79+
{{% notice style="warning" %}}
80+
**Exact path, no hierarchy.** OpenAPI 2.0 has no path nesting, so the target is
81+
matched literally: `swagger:parameters /pets/{id}` applies to `/pets/{id}` only —
82+
**not** to `/pets`. Path-item parameters also *co-exist* with operation-level
83+
ones rather than replacing them; if an operation declares a parameter with the
84+
same `(name, in)`, the operation's wins at resolution time per the OAS2 rule.
85+
{{% /notice %}}
86+
87+
To `$ref` an already-registered shared parameter into a path-item (instead of
88+
inlining a new one), use the reference form with a path target:
89+
`swagger:parameters /path <name>…` — the path-item analogue of the per-operation
90+
marker above.
91+
92+
## Shared responses
93+
94+
Responses share the same way. `swagger:response *` registers a struct at
95+
`#/responses/{name}` (keyed by the Go type name). The `*` is a synonym for the
96+
bare/named `swagger:response` form — its job is to mark the response as a
97+
*shared* one. Operations then name it in their `Responses:` block and it is
98+
emitted as a `$ref`.
99+
100+
{{< code file="concepts/sharedparams/sharedparams.go" lang="go" region="sharedresponse" >}}
101+
102+
The shared `ErrorResponse` lands in the top-level `responses` map:
103+
104+
{{< code file="concepts/sharedparams/testdata/responses.json" lang="json" >}}
105+
106+
Both routes write `default: ErrorResponse`, which resolves to a single shared
107+
`$ref` (visible as `responses.default.$ref` in the operation panes above) —
108+
one error envelope, defined once, referenced everywhere.
109+
110+
## Conflicts, duplicates & dangling references
111+
112+
The shared namespace is referenced **only by short name**, so codescan cannot
113+
silently rename a collision the way it
114+
[deconflicts model definitions]({{% relref "/shaping-the-output/resolving-name-conflicts" %}}).
115+
Instead it applies a deterministic, observable policy and reports every
116+
adjustment through `Options.OnDiagnostic` (the scan never fails on these — it
117+
keeps a valid spec and warns):
118+
119+
| Situation | Policy | Diagnostic |
120+
|---|---|---|
121+
| Two `swagger:parameters *` register the same name | **keep-first** (sorted by package path then position; never renamed) — later one dropped | `scan.shared-parameter-conflict` |
122+
| Two `swagger:response *` register the same name | keep-first; later one dropped | `scan.shared-response-conflict` |
123+
| A reference names a parameter no `*` registered | reference dropped (no dangling `$ref` emitted) | `scan.dangling-parameter-ref` |
124+
| An operation names an unregistered shared response | reference dropped | `scan.dangling-response-ref` |
125+
| A `* <opid>…` marker repeats an operation id | duplicate dropped | `scan.duplicate-target` |
126+
| A reference repeats a parameter name | collapses to a single `$ref` | `scan.duplicate-ref` |
127+
128+
{{% notice style="note" %}}
129+
The shared **parameters**, **responses** and **definitions** namespaces are
130+
independent: `#/parameters/Status`, `#/responses/Status` and
131+
`#/definitions/Status` can all coexist. The resolved (`name:`-overridden) name is
132+
the key, so references must use that name — not the Go field name. An `InputSpec`
133+
overlay entry seeds the namespace and wins any keep-first conflict.
134+
{{% /notice %}}
135+
136+
## What's next
137+
138+
- [Routes & operations]({{% relref "/tutorials/routes-and-operations" %}}) — the
139+
per-operation `swagger:parameters` / `swagger:response` basics.
140+
- [Pruning unused models]({{% relref "/shaping-the-output/pruning-unused-models" %}})
141+
— shared parameters and responses count as reachability roots when pruning.
142+
- [Keyword reference]({{% relref "/maintainers/keywords" %}}) — the exhaustive
143+
`parameters` / `responses` body grammars.
Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
// SPDX-License-Identifier: Apache-2.0
2+
3+
// Package sharedparams is the test-backed witness for the "Sharing
4+
// parameters & responses" tutorial (go-swagger#2632). It declares a small
5+
// pet API that reuses a header parameter and an error response across
6+
// several operations through the spec-level shared namespace
7+
// (#/parameters and #/responses).
8+
package sharedparams
9+
10+
// snippet:shared
11+
12+
// CommonHeaders registers a reusable header parameter at the spec top
13+
// level, #/parameters/X-Request-ID. The bare `*` target is register-only:
14+
// it publishes the parameter but does not, by itself, attach it to any
15+
// operation.
16+
//
17+
// swagger:parameters *
18+
type CommonHeaders struct {
19+
// RequestID correlates a request across services.
20+
//
21+
// in: header
22+
RequestID string `json:"X-Request-ID"` //nolint:tagliatelle // canonical HTTP header name
23+
}
24+
25+
// AuthHeader registers #/parameters/X-API-Key and, in the same breath,
26+
// $ref's it into the createPet operation — the convenient `* <opid>`
27+
// form for a small spec.
28+
//
29+
// swagger:parameters * createPet
30+
type AuthHeader struct {
31+
// APIKey authorises access.
32+
//
33+
// in: header
34+
// required: true
35+
APIKey string `json:"X-API-Key"` //nolint:tagliatelle // canonical HTTP header name
36+
}
37+
38+
// endsnippet:shared
39+
40+
// snippet:sharedresponse
41+
42+
// ErrorResponse is the common error envelope returned by every operation.
43+
//
44+
// swagger:response *
45+
type ErrorResponse struct {
46+
// in: body
47+
Body struct {
48+
// Code is a machine-readable error code.
49+
Code int `json:"code"`
50+
// Message is a human-readable error message.
51+
Message string `json:"message"`
52+
} `json:"body"`
53+
}
54+
55+
// endsnippet:sharedresponse
56+
57+
// CreatePetParams carries the request body for createPet; it is inlined
58+
// into the operation the normal way and sits alongside the $ref'd
59+
// X-API-Key header.
60+
//
61+
// swagger:parameters createPet
62+
type CreatePetParams struct {
63+
// in: body
64+
// required: true
65+
Body Pet `json:"body"`
66+
}
67+
68+
// Pet is the body model.
69+
//
70+
// swagger:model
71+
type Pet struct {
72+
// Name of the pet.
73+
Name string `json:"name"`
74+
}
75+
76+
// snippet:routes
77+
78+
// ListPets lists pets.
79+
//
80+
// The standalone reference marker on the next line pulls the shared
81+
// X-Request-ID parameter into this operation as a $ref. This is the
82+
// scaling channel: the shared struct need not enumerate every operation
83+
// that wants the parameter.
84+
//
85+
// swagger:route GET /pets pets listPets
86+
// swagger:parameters listPets X-Request-ID
87+
// Responses:
88+
//
89+
// default: ErrorResponse
90+
func ListPets() {}
91+
92+
// CreatePet creates a pet. Its X-API-Key comes from AuthHeader
93+
// (#/parameters/X-API-Key, $ref'd via `* createPet`); its body comes from
94+
// the inlined CreatePetParams.
95+
//
96+
// swagger:route POST /pets pets createPet
97+
// Responses:
98+
//
99+
// default: ErrorResponse
100+
func CreatePet() {}
101+
102+
// endsnippet:routes
103+
104+
// snippet:pathitem
105+
106+
// TenantHeader inlines a required header into the /pets/{id} path-item
107+
// itself, so every operation under that exact path inherits it. The
108+
// target is a literal path, and matching is exact — OAS2 has no path
109+
// hierarchy, so this does NOT apply to /pets.
110+
//
111+
// swagger:parameters /pets/{id}
112+
type TenantHeader struct {
113+
// Tenant scopes the request to a customer.
114+
//
115+
// in: header
116+
// required: true
117+
Tenant string `json:"X-Tenant"` //nolint:tagliatelle // canonical HTTP header name
118+
}
119+
120+
// GetPet fetches one pet. It declares no header of its own; X-Tenant
121+
// reaches it through the /pets/{id} path-item parameter above.
122+
//
123+
// swagger:route GET /pets/{id} pets getPet
124+
// Responses:
125+
//
126+
// default: ErrorResponse
127+
func GetPet() {}
128+
129+
// endsnippet:pathitem

0 commit comments

Comments
 (0)
⌂ 换网址