Class: DocsKit::OpenApi::Schema

Inherits:
Object
  • Object
show all
Defined in:
lib/docs_kit/open_api/schema.rb

Overview

A thin wrapper over one OpenAPI schema node that answers the three questions the render targets ask: what's its display type label, what FieldTable rows do its properties flatten to, and what example value does it synthesize.

All traversal is cycle-safe (a $ref that loops back stops descending) and depth-capped, because a real spec can be deeply nested or self-referential (Invoice.parent → Invoice).

Defined Under Namespace

Classes: Cursor

Constant Summary collapse

MAX_DEPTH =

How deep object/property flattening and example synthesis descend before stopping — guards both accidental depth and $ref cycles.

6

Instance Method Summary collapse

Constructor Details

#initialize(document, node) ⇒ Schema

Returns a new instance of Schema.



17
18
19
20
 
# File 'lib/docs_kit/open_api/schema.rb', line 17

def initialize(document, node)
  @document = document
  @node = node || {}
end

Instance Method Details

#example_value(depth: 0, seen: []) ⇒ Object

Synthesize an example value for this schema: the node's own example, else default, else the first enum value, else a per-type placeholder (recursing into object properties / array items). Cycle-safe via seen.



59
60
61
62
63
64
65
66
67
 
# File 'lib/docs_kit/open_api/schema.rb', line 59

def example_value(depth: 0, seen: [])
  node = merged
  return node["example"] if node.key?("example")
  return node["default"] if node.key?("default")
  return node["enum"].first if node["enum"].is_a?(Array) && !node["enum"].empty?
  return [] if depth >= MAX_DEPTH

  synthesize(node, depth, seen)
end

#rows(cursor: Cursor.root) ⇒ Object

Flatten this schema's properties into FieldTable-ready rows. Nested object properties dot their names (customer.id); required is read from the object's required list. The Cursor threads prefix/depth/seen recursion.



45
46
47
48
49
50
51
52
53
54
 
# File 'lib/docs_kit/open_api/schema.rb', line 45

def rows(cursor: Cursor.root)
  node = merged
  return [] if cursor.depth >= MAX_DEPTH
  return [] unless node["properties"].is_a?(Hash)

  required = Array(node["required"])
  node["properties"].flat_map do |name, prop_node|
    property_rows(prop_node, name: name, required: required.include?(name), cursor: cursor)
  end
end

#type_label ⇒ Object

A human display type for a FieldTable "Type" cell:

"string", "integer", "array of string", "usd | eur | gbp" (enum),
"one of: A | B" (oneOf/anyOf), "object".


25
26
27
28
29
30
31
32
 
# File 'lib/docs_kit/open_api/schema.rb', line 25

def type_label
  node = merged
  return enum_label(node["enum"]) if node["enum"]
  return one_of_label(node) if node["oneOf"] || node["anyOf"]
  return "array of #{Schema.new(@document, deref(node['items'])).type_label}" if array?(node)

  node["type"] || "object"
end