Class: DocsKit::OpenApi::Document

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

Overview

A parsed OpenAPI 3.x document. Indexes every path/verb operation and offers two lookups — by operationId, or by (method, path) for specs that omit ids — plus the shared local-$ref resolver every Operation/Schema reads through.

Keys stay Strings internally (that's how both YAML and JSON parse), so the model never guesses at symbol/string key shape.

Constant Summary collapse

HTTP_METHODS =

The HTTP verbs an OpenAPI path item may carry, lower-cased as they appear in the spec.

%w[get put post delete options head patch trace].freeze

Instance Method Summary collapse

Constructor Details

#initialize(raw) ⇒ Document

Returns a new instance of Document.



16
17
18
 
# File 'lib/docs_kit/open_api/document.rb', line 16

def initialize(raw)
  @raw = raw
end

Instance Method Details

#deref(node) ⇒ Object

Follow a node's $ref (if any) one hop to the referenced node; a node without a $ref is returned unchanged.



49
50
51
 
# File 'lib/docs_kit/open_api/document.rb', line 49

def deref(node)
  node.is_a?(Hash) && node.key?("$ref") ? resolve_ref(node["$ref"]) : node
end

#operation(id_or_method, path = nil) ⇒ Object

Look up an operation. Two forms:

operation("createInvoice")           — by operationId
operation(:post, "/v1/invoices")     — by HTTP method + path

Raises OperationNotFound (naming the available ids) when nothing matches.



24
25
26
27
 
# File 'lib/docs_kit/open_api/document.rb', line 24

def operation(id_or_method, path = nil)
  found = path.nil? ? by_operation_id(id_or_method) : by_method_and_path(id_or_method, path)
  found || raise(OperationNotFound, not_found_message(id_or_method, path))
end

#operations ⇒ Object

Every operation across every path, in document order.



30
31
32
 
# File 'lib/docs_kit/open_api/document.rb', line 30

def operations
  @operations ||= build_operations
end

#resolve_ref(ref) ⇒ Object

Resolve a local $ref ("#/components/schemas/Foo") to the referenced node. An external/remote ref (not starting "#/") raises UnsupportedRef. Used by Operation and Schema so ref handling lives in exactly one place.

Raises:



37
38
39
40
41
42
43
44
45
 
# File 'lib/docs_kit/open_api/document.rb', line 37

def resolve_ref(ref)
  raise UnsupportedRef, "external/remote $ref is not supported: #{ref}" unless ref.start_with?("#/")

  ref.delete_prefix("#/").split("/").reduce(@raw) do |node, segment|
    # JSON Pointer escaping: ~1 → "/", ~0 → "~".
    key = segment.gsub("~1", "/").gsub("~0", "~")
    node.is_a?(Hash) ? node[key] : nil
  end
end