Documentation
¶
Overview ¶
Package paramutil resolves parameter $ref values against a document's reusable parameter definitions.
The parser preserves $ref values verbatim so documents round-trip losslessly, which means a referenced parameter arrives with empty Name and In fields. Any analysis that keys off those fields — path template consistency checks, for example — must resolve the reference first or it will conclude the parameter declares nothing at all.
Index ¶
- func NeedsRequiredTrue(param *parser.Parameter) bool
- type Reason
- type Resolver
- func (r Resolver) Classify(param *parser.Parameter) (*parser.Parameter, Reason)
- func (r Resolver) DeclaredPathParams(lists ...[]*parser.Parameter) (declared map[string]bool, complete bool)
- func (r Resolver) Defines(ref string) bool
- func (r Resolver) Resolve(param *parser.Parameter) (*parser.Parameter, bool)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NeedsRequiredTrue ¶ added in v1.56.0
NeedsRequiredTrue reports whether param is an in: path parameter that omits required: true. Both OAS 2.0 and 3.x demand the field be present and true for path parameters and permit no other value, so a parameter this returns true for is invalid in every version and repairable without judgment or loss.
A parameter carrying a $ref is skipped. References are preserved verbatim so documents round-trip losslessly, which leaves every sibling field — Required included — empty on the reference itself; the defect, if there is one, belongs to the definition it names. Callers check the reusable definitions in their own right, so a use site skipped here is still covered exactly once.
Types ¶
type Reason ¶
type Reason int
Reason explains the outcome of following a parameter's $ref chain.
Only ReasonExternal is genuinely unknowable. The rest are defects in the document, so a caller that suppresses a diagnostic because resolution failed must make sure something reports the reason instead — silence is only warranted for ReasonExternal.
const ( // ReasonResolved means the chain reached an inline parameter. ReasonResolved Reason = iota // ReasonExternal means the $ref points outside this document. This package // never loads other files or URLs, and the parser leaves such references // unexpanded by default, so nothing has resolved them. ReasonExternal // ReasonNotAParameter means a local $ref that names no parameter definition // in this document — it either dangles or names a different kind of // component. Distinguishing those two needs the document's full set of // valid references, which this package does not have. ReasonNotAParameter // ReasonCycle means the chain revisits a reference it already followed. ReasonCycle // ReasonTooDeep means the chain exceeded maxRefDepth without repeating, // so it is not a cycle — just longer than this package will follow. ReasonTooDeep )
type Resolver ¶
Resolver maps local parameter $ref values to the definitions they point at. The zero value (a nil Resolver) is usable: it resolves inline parameters and reports every $ref as unresolvable.
func NewOAS2Resolver ¶
func NewOAS2Resolver(doc *parser.OAS2Document) Resolver
NewOAS2Resolver builds a Resolver over an OAS 2.0 document's root-level parameters, keyed by "#/parameters/{name}".
func NewOAS3Resolver ¶
func NewOAS3Resolver(doc *parser.OAS3Document) Resolver
NewOAS3Resolver builds a Resolver over an OAS 3.x document's components.parameters, keyed by "#/components/parameters/{name}".
func (Resolver) Classify ¶
Classify follows param's $ref chain and reports what happened. The returned parameter is non-nil only for ReasonResolved.
Callers that only need "did it resolve" should use Resolve. Classify exists for callers that suppress diagnostics on failure and therefore owe the user an explanation of why.
func (Resolver) DeclaredPathParams ¶
func (r Resolver) DeclaredPathParams(lists ...[]*parser.Parameter) (declared map[string]bool, complete bool)
DeclaredPathParams returns the names of every path parameter declared across the given parameter lists, resolving local $ref values along the way. Lists are typically the path item's parameters followed by the operation's. The names collapse into a single set rather than the operation's list shadowing the path item's, because an operation-level parameter overrides a path-level one of the same name and location — both contribute the same name, so a union is sufficient here. This is not a general implementation of that override.
complete reports whether every parameter resolved. When it is false the returned set is a lower bound — some parameter in the list may declare a name that is not present — so callers must not report a path template parameter as undeclared based on it.
declared is nil when no path parameter is declared, which is the common case: this runs per path item and per operation, and most of them declare none. A nil set reads and ranges exactly like an empty one, so callers need no special case — but they must only read it, never assign into it.
func (Resolver) Defines ¶
Defines reports whether ref names a parameter definition in this resolver.
This answers a narrower question than Resolve: it inspects only the ref's immediate target, so it stays true for a reference to a parameter whose own $ref chain is broken further down. Callers distinguishing "this is not a parameter at all" from "this is a parameter that fails to resolve" need that distinction — the two are different defects.
func (Resolver) Resolve ¶
Resolve returns the effective definition for param, following local $ref hops until it reaches an inline parameter.
Returns false whenever the chain cannot be followed. Callers must treat that as "unknown" rather than "declares nothing" — the whole point of this package is that the two are not the same. Use Classify when the distinction between the ways it can fail matters, which it does for anything that reports diagnostics.
Source Files