Class: RSpec::Rails::Api::OpenApiRenderer

Inherits:
Object
  • Object
show all
Defined in:
lib/rspec/rails/api/open_api_renderer.rb

Overview

Class to render metadata. Example:

```rb
renderer = RSpec::Rails::Api::OpenApiRenderer.new
renderer.merge_context(example_context)
renderer.write_files
```

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ OpenApiRenderer

Returns a new instance of OpenApiRenderer.



20
21
22
23
24
25
26
27
28
29
30
31
 
# File 'lib/rspec/rails/api/open_api_renderer.rb', line 20

def initialize
  @metadata       = { resources: {}, entities: {} }
  @api_infos      = {}
  @api_servers    = []
  @api_paths      = {}
  @api_components = {}
  @api_tags       = []
  @api_contact    = {}
  @api_license    = {}
  @api_security   = {}
  @redactables    = {}
end

Instance Attribute Details

#api_description=(value) ⇒ Object (writeonly)

rubocop:disable Metrics/ClassLength



17
18
19
 
# File 'lib/rspec/rails/api/open_api_renderer.rb', line 17

def api_description=(value)
  @api_description = value
end

#api_servers=(value) ⇒ Object

rubocop:disable Metrics/ClassLength



17
18
19
 
# File 'lib/rspec/rails/api/open_api_renderer.rb', line 17

def api_servers=(value)
  @api_servers = value
end

#api_title=(value) ⇒ Object (writeonly)

rubocop:disable Metrics/ClassLength



17
18
19
 
# File 'lib/rspec/rails/api/open_api_renderer.rb', line 17

def api_title=(value)
  @api_title = value
end

#api_tos=(value) ⇒ Object (writeonly)

rubocop:disable Metrics/ClassLength



17
18
19
 
# File 'lib/rspec/rails/api/open_api_renderer.rb', line 17

def api_tos=(value)
  @api_tos = value
end

#api_version=(value) ⇒ Object (writeonly)

rubocop:disable Metrics/ClassLength



17
18
19
 
# File 'lib/rspec/rails/api/open_api_renderer.rb', line 17

def api_version=(value)
  @api_version = value
end

#redactables ⇒ Object (readonly)

Returns the value of attribute redactables.



18
19
20
 
# File 'lib/rspec/rails/api/open_api_renderer.rb', line 18

def redactables
  @redactables
end

Instance Method Details

#add_security_scheme(reference, definition) ⇒ Object

Adds a security scheme definition to the API documentation

Parameters:



42
43
44
45
46
 
# File 'lib/rspec/rails/api/open_api_renderer.rb', line 42

def add_security_scheme(reference, definition)
  raise "Security scheme #{reference} is already defined" if @api_security.key? reference

  @api_security[reference] = definition
end

#api_contact=(name: nil, email: nil, url: nil) ⇒ void

This method returns an undefined value.

Sets the contact field

Parameters:

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

    Contact name

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

    Contact Email

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

    Contact URL



113
114
115
116
117
 
# File 'lib/rspec/rails/api/open_api_renderer.rb', line 113

def api_contact=(name: nil, email: nil, url: nil)
  @api_contact[:name]  = name if name
  @api_contact[:email] = email if email
  @api_contact[:url]   = url if url
end

#api_license=(name: nil, url: nil) ⇒ void

This method returns an undefined value.

Sets the license field

Parameters:

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

    License name

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

    License URL



126
127
128
129
 
# File 'lib/rspec/rails/api/open_api_renderer.rb', line 126

def api_license=(name: nil, url: nil)
  @api_license[:name] = name if name
  @api_license[:url] = url if url
end

#merge_context(context, dump_metadata: false) ⇒ void

This method returns an undefined value.

Merges example context definition with the renderer data

Parameters:

  • context (Hash) —

    Metadata hash

  • dump_metadata (Boolean) (defaults to: false) —

    Saves the raw metadata in ‘tmp/rra_metadata.yaml` for debugging



55
56
57
58
59
60
 
# File 'lib/rspec/rails/api/open_api_renderer.rb', line 55

def merge_context(context, dump_metadata: false)
  @metadata[:resources].deep_merge! context.respond_to?(:resources) ? context.resources : context[:resources]

  # Save context for debug and fixtures
  File.write ::Rails.root.join('tmp', 'rra_metadata.yaml'), @metadata.to_yaml if dump_metadata
end

#prepare_metadata ⇒ Hash

Extracts metadata from context to generate an OpenAPI structure

Returns:

  • (Hash) —

    The OpenAPI structure



91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/rspec/rails/api/open_api_renderer.rb', line 91

def prepare_metadata
  extract_metadata
  # Example: https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore-expanded.yaml
  hash = {
    openapi:    '3.0.0',
    info:       @api_infos,
    servers:    @api_servers,
    paths:      @api_paths,
    components: @api_components,
    tags:       @api_tags,
  }
  JSON.parse(hash.to_json)
end

#redact_responses(pairs) ⇒ Object 



33
34
35
 
# File 'lib/rspec/rails/api/open_api_renderer.rb', line 33

def redact_responses(pairs)
  @redactables = pairs
end

#write_files(path = nil, only: %i[yaml json])) ⇒ void

This method returns an undefined value.

Write OpenAPI files

Parameters:

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

    Where to save the files. Defaults to ‘/tmp/rspec_api_rails.*` when unset

  • only ([Symbol]) (defaults to: %i[yaml json])) —

    Formats to save the file to. Allowed values are ‘:yaml` and `:json`



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/rspec/rails/api/open_api_renderer.rb', line 69

def write_files(path = nil, only: %i[yaml json])
  return unless write_file? RSpec.world.filtered_examples

  path ||= ::Rails.root.join('tmp', 'rspec_api_rails')

  metadata = prepare_metadata

  file_types = %i[yaml json]
  only.each do |type|
    next unless file_types.include? type

    data = metadata.to_yaml if type == :yaml
    data = JSON.pretty_generate(metadata) if type == :json

    File.write "#{path}.#{type}", data
  end
end