feat: inject a custom document loader into schema/spec validation

[fredbi]

Building a schema validator expands the schema's $ref, and validating a specification resolves and expands $ref (schemas, parameters, responses, and the whole-spec expansion). All of these resolved documents through the spec package's global loader, with no way for a caller to supply their own.

Add WithPathLoader, an option-aware loader on SchemaValidatorOptions, consumed by every path that loads documents during validation:

• newSchemaValidator uses spec.ExpandSchemaWithOptions (instead of the default-settings ExpandSchema).
• resolveParam / expandResponseRef use spec.ExpandParameterWithOptions and spec.ExpandResponseWithOptions.
• SpecValidator.resolveRef passes the loader through spec.ResolveRefWithBase.
• validateReferencesValid passes it to loads.Document.Expanded (no-op when unset: loads falls back to the document's own loader).
• NewSpecValidator and the package-level Spec now accept ...Option, applied to the internal schema options after the built-in defaults, so a caller can inject the loader into spec validation. Backward compatible: existing two-argument calls are unaffected.

The injected loader may carry any go-openapi/swag/loading options — a custom HTTP client or timeout, authentication or custom headers, an embedded or rooted file system, and so on. One important use is confining loading of untrusted input (loading.WithRoot to confine local reads, loading.WithHTTPClient to restrict remote fetches, or a restricted loader from go-openapi/loads), which closes the arbitrary-file-read / SSRF surface that the unsandboxed default otherwise exposes. Left unset, behavior is unchanged.

Bumps spec to v0.22.9 (for the option-aware expanders), analysis to v0.25.5, loads to v0.25.0 and swag to v0.27.3.

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.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.37%. Comparing base (cbf963a) to head (58f6939).
⚠️ Report is 1 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #272      +/-   ##
==========================================
+ Coverage   92.35%   92.37%   +0.01%     
==========================================
  Files          24       24              
  Lines        3272     3280       +8     
==========================================
+ Hits         3022     3030       +8     
  Misses        165      165              
  Partials       85       85              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.