Oasis.Spec.OpenAPIRefResolver (oasis v0.7.0)

Copy Markdown View Source

Resolves the structural OpenAPI Reference Objects selected by Oasis preparation.

This module is intentionally OpenAPI-aware and deliberately not a generic JSON Schema $ref expander. It selects structural OpenAPI Reference Object locations such as:

  • Path Item Objects
  • Parameter Objects
  • Request Body Objects
  • Response Objects
  • Security Scheme Objects

The generic $ref mechanics are delegated to JSONSchex.Ref.resolve_selected/2: URI resolution, JSON Pointer lookup, external loading, base URI propagation, and cycle detection.

Schema Object $ref values are not selected here. They are preserved so JSONSchex.bundle_fragment/2 can resolve the schema graph with proper JSON Schema Draft 2020-12 semantics.

Selection rules

openapi_reference_object?/2 returns true only for the following structural OpenAPI Reference Object locations, and false everywhere else (including any Schema Object location):

  • #/paths/{url} — Path Item Object
  • #/paths/{url}/parameters/{i} — path-item-level Parameter Object
  • #/paths/{url}/{verb}/parameters/{i} — operation-level Parameter Object
  • #/paths/{url}/{verb}/requestBody — Request Body Object
  • #/paths/{url}/{verb}/responses/{status} — Response Object
  • #/components/securitySchemes/{name} — Security Scheme Object

where {url} starts with / and {verb} is one of the standard HTTP methods Oasis generates routes for (get, head, post, put, patch, delete, options). Anything outside this list — Schema Object refs, callbacks, links, examples, server objects, etc. — is left intact.

Loader

External OpenAPI references (e.g. ./common.yaml#/components/parameters/UserId) are loaded through JSONSchex.Ref.resolve_selected/2's :loader option. resolve/2 defaults :loader to &Oasis.Spec.Document.load_external/1 via Keyword.put_new/3, so callers may override it by passing their own loader. JSONSchex accepts {:ok, schema} or an atom-keyed metadata wrapper {:ok, %{document: schema, base_uri: base_uri}}.

JSONSchex owns resource base propagation for loaded documents. Oasis's role in this resolver is limited to choosing which OpenAPI Reference Objects should be resolved before generation.

Caller opts contract

resolve/2 is deliberately opinionated about the options it forwards to JSONSchex.Ref.resolve_selected/2:

  • :select — force-overridden to &openapi_reference_object?/2. A caller-supplied :select is silently discarded. This is intentional: the whole point of this module is to fix the OpenAPI selection policy so the Oasis/JSONSchex boundary (Schema Object refs are preserved for JSONSchex) stays consistent across all callers.
  • :loader — defaulted via Keyword.put_new/3. Callers may override it with a custom loader, or pass loader: nil to opt out of external loading entirely.
  • :base_uri — caller-controlled. Used by JSONSchex to resolve relative external OpenAPI refs. The resolve/1 arity-1 form sets it to document.source_path automatically; the arity-2 form takes whatever the caller passes.
  • Any other option recognized by JSONSchex.Ref.resolve_selected/2 is forwarded unchanged.

Summary

Functions

openapi_reference_object?(arg1, arg2)

Returns true when the path/node pair represents an OpenAPI Reference Object location that Oasis needs to dereference before generation.

resolve(document)

Resolves OpenAPI Reference Objects inside a loaded Oasis.Spec.Document.

resolve(schema, opts \\ [])

Resolves OpenAPI Reference Objects in a decoded OpenAPI map.

Functions

openapi_reference_object?(arg1, arg2)

@spec openapi_reference_object?(list(), map()) :: boolean()

Returns true when the path/node pair represents an OpenAPI Reference Object location that Oasis needs to dereference before generation.

Schema Object locations intentionally return false so JSON Schema refs remain available for JSONSchex fragment compilation/bundling.

resolve(document)

@spec resolve(Oasis.Spec.Document.t()) :: Oasis.Spec.Document.t()

Resolves OpenAPI Reference Objects inside a loaded Oasis.Spec.Document.

The returned document keeps Schema Object refs intact, but selected path items, parameters, request bodies, responses, and security schemes are dereferenced. Response refs are prepared eagerly even though current request-handler generation does not otherwise consume response schemas; a missing selected response resource therefore remains an invalid specification.

resolve(schema, opts \\ [])

@spec resolve(
  map(),
  keyword()
) :: map()

Resolves OpenAPI Reference Objects in a decoded OpenAPI map.

Options

  • :base_uri — file path or URI used to resolve relative external OpenAPI refs. Required when the document contains external refs.
  • :loader — optional. Defaults to &Oasis.Spec.Document.load_external/1. Pass a custom function to use your own loader, or nil to disable external loading. Success may return {:ok, schema} or an atom-keyed metadata wrapper {:ok, %{document: schema, base_uri: base_uri}}.
  • Any other option recognized by JSONSchex.Ref.resolve_selected/2 is forwarded unchanged.

Reserved options

  • :select — force-overridden to &openapi_reference_object?/2. A caller-supplied :select is silently discarded. See the moduledoc "Caller opts contract" section for the rationale.