Class: JekyllOpenAPI::Reference

Inherits:
Object
  • Object
show all
Defined in:
lib/jekyll_openapi/reference.rb

Overview

Lazy, name-preserving stand-in for a JSON $ref.

The Dereferencer replaces each {"$ref" => ...} node with a Reference rather than inlining its target. This keeps the reference graph — and the component name — intact, which buys three things the old inlining threw away:

* renderers/templates can link to a named schema instead of always
expanding it (see Schema#name);
* a schema reused N times resolves to one shared object, not N deep copies;
* recursion terminates, because targets are only followed on demand.

For read access a Reference transparently delegates to its resolved target (ref["type"], ref.dig("schema", "pattern"), iteration), so plain hash-walking templates keep working unchanged. #reference?, #name and #ref expose the pointer for code that wants to link rather than follow.

Defined Under Namespace

Classes: Context

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(ref, context, overrides = {}) ⇒ Reference

Returns a new instance of Reference.

Parameters:

  • ref (String) —

    the raw pointer, e.g. "#/components/schemas/Pet"

  • context (Context) —

    shared resolution state

  • overrides (Hash) (defaults to: {}) —

    sibling summary/description overriding the target



32
33
34
35
36
 
# File 'lib/jekyll_openapi/reference.rb', line 32

def initialize(ref, context, overrides = {})
  @ref = ref
  @context = context
  @overrides = overrides
end

Instance Attribute Details

#overrides ⇒ Object (readonly)

Returns the value of attribute overrides.



27
28
29
 
# File 'lib/jekyll_openapi/reference.rb', line 27

def overrides
  @overrides
end

#ref ⇒ Object (readonly)

Returns the value of attribute ref.



27
28
29
 
# File 'lib/jekyll_openapi/reference.rb', line 27

def ref
  @ref
end

Instance Method Details

#[](key) ⇒ Object

--- hash-like read delegation to the resolved target --------------------



69
70
71
72
73
 
# File 'lib/jekyll_openapi/reference.rb', line 69

def [](key)
  return @ref if key == "$ref"
  target = resolve
  mapping?(target) ? target[key] : nil
end

#dig(key, *rest) ⇒ Object 



89
90
91
92
93
 
# File 'lib/jekyll_openapi/reference.rb', line 89

def dig(key, *rest)
  value = self[key]
  return value if rest.empty? || value.nil?
  value.respond_to?(:dig) ? value.dig(*rest) : nil
end

#each(&block) ⇒ Object Also known as: each_pair 



95
96
97
98
 
# File 'lib/jekyll_openapi/reference.rb', line 95

def each(&block)
  target = resolve
  target.each(&block) if target.respond_to?(:each)
end

#external? ⇒ Boolean

True when the pointer targets another file or URL (unsupported for now).

Returns:

  • (Boolean) 


48
49
50
 
# File 'lib/jekyll_openapi/reference.rb', line 48

def external?
  !local?
end

#fetch(key, *default) ⇒ Object

Raises:

  • (KeyError) 


82
83
84
85
86
87
 
# File 'lib/jekyll_openapi/reference.rb', line 82

def fetch(key, *default)
  return self[key] if key?(key)
  return yield(key) if block_given?
  return default.first unless default.empty?
  raise KeyError, "key not found: #{key.inspect}"
end

#key?(key) ⇒ Boolean Also known as: include?

Returns:

  • (Boolean) 


75
76
77
78
79
 
# File 'lib/jekyll_openapi/reference.rb', line 75

def key?(key)
  return true if key == "$ref"
  target = resolve
  mapping?(target) && target.key?(key)
end

#local? ⇒ Boolean

True when the pointer is local to the current document (starts with "#").

Returns:

  • (Boolean) 


43
44
45
 
# File 'lib/jekyll_openapi/reference.rb', line 43

def local?
  @ref.is_a?(String) && @ref.start_with?("#")
end

#name ⇒ Object

Component name, e.g. "Pet" for "#/components/schemas/Pet"; nil when external.



53
54
55
56
 
# File 'lib/jekyll_openapi/reference.rb', line 53

def name
  return nil unless local?
  @name ||= JSONPointer.unescape(@ref.delete_prefix("#").split("/").last)
end

#reference? ⇒ Boolean

Returns:

  • (Boolean) 


38
39
40
 
# File 'lib/jekyll_openapi/reference.rb', line 38

def reference?
  true
end

#resolve ⇒ Object

The target node, lazily resolved and memoized, with summary/description overrides applied. Nested $refs inside it are themselves References. Returns nil (warning once) for external or unresolvable pointers.



61
62
63
64
65
 
# File 'lib/jekyll_openapi/reference.rb', line 61

def resolve
  return @resolved if @resolved_computed
  @resolved_computed = true
  @resolved = compute_resolution
end

#to_hash ⇒ Object Also known as: to_h

A Reference merges like the hash it stands for (used by Parameters.merge).



108
109
110
111
 
# File 'lib/jekyll_openapi/reference.rb', line 108

def to_hash
  target = resolve
  target.is_a?(Hash) ? target : { "$ref" => @ref }
end

#to_json(*args) ⇒ Object

Serialize back to a $ref node. Finite by construction (it never expands the target), so oapi_dereference | jsonify stays bounded even for recursive schemas, and round-trips to a valid OpenAPI reference.



117
118
119
 
# File 'lib/jekyll_openapi/reference.rb', line 117

def to_json(*args)
  { "$ref" => @ref }.to_json(*args)
end

#to_liquid ⇒ Object

Liquid indexes us like the hash we stand for (it calls #to_liquid on every value and does not patch arbitrary objects), so hand it back ourselves.



103
104
105
 
# File 'lib/jekyll_openapi/reference.rb', line 103

def to_liquid
  self
end