Class: JekyllOpenAPI::Document

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

Overview

Navigable object model over a parsed OpenAPI document.

Absorbs the spec-aware traversal that would otherwise live in templates: enumerating operations (including x- extension methods), filtering by tag, merging path-level with operation-level parameters, and surfacing the component collections (schemas, security schemes, servers) that a reference page needs. $refs stay navigable but keep their names (see Reference), so templates can link named schemas instead of inlining them.

Constant Summary collapse

HTTP_METHODS = 
%w[get put post delete options head patch trace].freeze
PATH_ITEM_FIELDS = 
%w[summary description servers parameters $ref].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data, logger: JekyllOpenAPI.logger) ⇒ Document

Returns a new instance of Document.

Parameters:

  • data (Hash) —

    a parsed OpenAPI document (dereferenced or not)



23
24
25
26
 
# File 'lib/jekyll_openapi/document.rb', line 23

def initialize(data, logger: JekyllOpenAPI.logger)
  @data = data
  @logger = logger
end

Instance Attribute Details

#data ⇒ Object (readonly)

Returns the value of attribute data.



20
21
22
 
# File 'lib/jekyll_openapi/document.rb', line 20

def data
  @data
end

Class Method Details

.load_file(path, logger: JekyllOpenAPI.logger) ⇒ Object

Convenience loader for YAML or JSON files



29
30
31
32
33
34
35
36
 
# File 'lib/jekyll_openapi/document.rb', line 29

def self.load_file(path, logger: JekyllOpenAPI.logger)
  data = if File.extname(path) == ".json"
    JSON.parse(File.read(path))
  else
    YAML.safe_load_file(path, aliases: true)
  end
  new(data, logger: logger)
end

Instance Method Details

#components ⇒ Object

The whole components object. Prefer the named helpers below.



67
68
69
 
# File 'lib/jekyll_openapi/document.rb', line 67

def components
  dereferenced["components"] || {}
end

#dereferenced ⇒ Hash

Returns a copy of the document in which every local $ref is a lazy Reference (navigable, name-preserving, resolved on demand); memoized.

Returns:

  • (Hash) —

    a copy of the document in which every local $ref is a lazy Reference (navigable, name-preserving, resolved on demand); memoized



40
41
42
 
# File 'lib/jekyll_openapi/document.rb', line 40

def dereferenced
  @dereferenced ||= Dereferencer.new(@data, logger: @logger).dereference
end

#info ⇒ Object 



44
45
46
 
# File 'lib/jekyll_openapi/document.rb', line 44

def info
  dereferenced["info"] || {}
end

#operations(tag: nil) ⇒ Object

Flat list of every operation in the document, in path order. x--prefixed extension methods (e.g. webDAV verbs) are included, with the prefix stripped in "method" and kept in "raw_method".

Each entry is a string-keyed Hash (Liquid-friendly):

"path"               [String]  e.g. "/scenes/{scene}"
"method"             [String]  e.g. "get" or "mkcol"
"raw_method"         [String]  e.g. "get" or "x-mkcol"
"operation"          [Hash]    the Operation object
"parameters"         [Array]   path-level and operation-level parameters, merged
"grouped_parameters" [Hash]    same, grouped by location (see Parameters.group)

Parameters:

  • tag (String, nil) (defaults to: nil) —

    only operations tagged with this tag



100
101
102
103
104
 
# File 'lib/jekyll_openapi/document.rb', line 100

def operations(tag: nil)
  @operations ||= build_operations
  return @operations unless tag
  @operations.select { |op| Array(op["operation"]["tags"]).include?(tag) }
end

#operations_by_tag ⇒ Hash{String => Array}

Returns tag name => operations, following the tags declaration order.

Returns:

  • (Hash{String => Array}) —

    tag name => operations, following the tags declaration order



107
108
109
 
# File 'lib/jekyll_openapi/document.rb', line 107

def operations_by_tag
  tags.to_h { |t| [t["name"], operations(tag: t["name"])] }
end

#paths ⇒ Object 



52
53
54
 
# File 'lib/jekyll_openapi/document.rb', line 52

def paths
  dereferenced["paths"] || {}
end

#schemas ⇒ Hash{String => Object}

Named schema map, e.g. for a "Models" reference section. Values keep their nested $refs as References, so a template can render each schema's body and cross-link by name (see Schema#name) rather than inline everything.

Returns:

  • (Hash{String => Object}) 


76
77
78
 
# File 'lib/jekyll_openapi/document.rb', line 76

def schemas
  components["schemas"] || {}
end

#security ⇒ Object

Top-level security requirements applied to every operation by default.



62
63
64
 
# File 'lib/jekyll_openapi/document.rb', line 62

def security
  dereferenced["security"] || []
end

#security_schemes ⇒ Hash{String => Object}

Named security scheme map (apiKey/http/oauth2/openIdConnect definitions).

Returns:

  • (Hash{String => Object}) 


82
83
84
 
# File 'lib/jekyll_openapi/document.rb', line 82

def security_schemes
  components["securitySchemes"] || {}
end

#servers ⇒ Object

Declared servers (empty when the document omits them).



57
58
59
 
# File 'lib/jekyll_openapi/document.rb', line 57

def servers
  dereferenced["servers"] || []
end

#tags ⇒ Object 



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

def tags
  dereferenced["tags"] || []
end