|
| 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. |
0 commit comments