Class: RSpec::Apidoc

Inherits:
Core::Formatters::BaseFormatter
  • Object
show all
Includes:
ERB::Util
Defined in:
lib/rspec/apidoc.rb

Overview

Our formatter class.

We’re using the formatter as the hooks do not allow to report when the test runner is done.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.add(spec, example) ⇒ Hash

Parses and stores relevant to our docs data in the example metadata

rubocop:disable Metrics/AbcSize,Metrics/MethodLength

Returns:

  • (Hash) —

    the metadata that was added



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/rspec/apidoc.rb', line 89

def self.add(spec, example)
  request_body = parse_json_safely(spec.request.body.string)
  response_body = parse_json_safely(spec.response.body)

  if spec.request.controller_instance
    action_name = spec.request.controller_instance.action_name
    action_method = spec.request.controller_instance.method(action_name)
    # Remove any `@param` or `@return` lines
    action_comment = action_method.comment
      .gsub(/^#(\s+)?$/, "\n").gsub(/^#(\s+)?/, '').gsub(/^@.*$/, '')
    controller_class = spec.request.controller_class
    controller_comment = nil

    if action_method.respond_to?(:class_comment)
      controller_comment = action_method.class_comment.gsub(
        /.*frozen_string_literal:.*/, ''
      ).gsub(/^#(\s+)?$/, "\n").gsub(/^#(\s+)?/, '').gsub(/^@.*$/, '')
    end
  else
    action_comment = nil
    controller_comment = nil
    controller_class = spec.request.path
    action_name = spec.request.method
  end

  example.metadata[:apidoc_data] = {
    description: example.metadata[:full_description],

    controller_class: controller_class,
    controller_comment: controller_comment,
    action_name: action_name,
    action_comment: action_comment,

    content_type: spec.request.content_type,
    auth_header: auth_header(spec.request.headers),
    method: spec.request.method,
    path: spec.request.path,
    query: spec.request.query_parameters.to_param,
    request_body: request_body,

    status: spec.response.status,
    response_content_type: spec.response.content_type,
    response_body: response_body
  }
end

.auth_header(headers) ⇒ Object

Returns the API authentication header callback result

Parameters:

  • headers (ActionDispatch::Http::Headers) —

    object

Returns:

  • (Object) 


73
74
75
 
# File 'lib/rspec/apidoc.rb', line 73

def self.auth_header(headers)
  RSpec.configuration.apidoc_auth_header.call(headers)
end

.parse_json_safely(obj) ⇒ Object

Returns a parsed JSON object

Parameters:

  • obj (Object) —

    an object to parse as JSON

Returns:

  • (Object) 


140
141
142
143
144
 
# File 'lib/rspec/apidoc.rb', line 140

def self.parse_json_safely(obj)
  JSON.parse(obj)
rescue StandardError
  obj.to_s
end

Instance Method Details

#close(_notification) ⇒ Integer

Formatter callback, generates the HTML from the metadata we stored

Returns:

  • (Integer) —

    size of the new file.



163
164
165
166
167
168
 
# File 'lib/rspec/apidoc.rb', line 163

def close(_notification)
  return if examples.empty?

  erb = ERB.new(File.read(template_path), trim_mode: '-')
  File.write(output_filename, erb.result(self.binding))
end

#description ⇒ String

Returns the description for our docs

Returns:

  • (String) 


44
45
46
 
# File 'lib/rspec/apidoc.rb', line 44

def description
  RSpec.configuration.apidoc_description
end

#example_passed(notification) ⇒ Hash

Formatter callback, stores the example metadata for later to be used

Returns:

  • (Hash) —

    the metadata that was stored



149
150
151
152
153
154
155
156
157
158
 
# File 'lib/rspec/apidoc.rb', line 149

def example_passed(notification)
  apidoc_data = notification.example.metadata[:apidoc_data]

  return if apidoc_data.nil?

  controller_name = apidoc_data[:controller_class].to_s
  controller_examples = examples[controller_name] ||= {}
  controller_examples[apidoc_data[:action_name]] ||= []
  controller_examples[apidoc_data[:action_name]].append(apidoc_data)
end

#examples ⇒ Array

Returns the collected examples, sorted

Returns:

  • (Array) —

    a list of [Hash] items



80
81
82
83
 
# File 'lib/rspec/apidoc.rb', line 80

def examples
  @examples ||= {}
  @examples = @examples.sort.to_h
end

#host ⇒ String

Returns the API host used to generate the ‘curl` commands

Returns:

  • (String) 


65
66
67
 
# File 'lib/rspec/apidoc.rb', line 65

def host
  RSpec.configuration.apidoc_host
end

#output_filename ⇒ String

Returns the final document path for our docs

Returns:

  • (String) 


58
59
60
 
# File 'lib/rspec/apidoc.rb', line 58

def output_filename
  RSpec.configuration.apidoc_output_filename
end

#template_path ⇒ String

Returns the template path used to render our docs

Returns:

  • (String) 


51
52
53
 
# File 'lib/rspec/apidoc.rb', line 51

def template_path
  RSpec.configuration.apidoc_template_path
end

#title ⇒ String

Returns the title for our docs

Returns:

  • (String) 


37
38
39
 
# File 'lib/rspec/apidoc.rb', line 37

def title
  RSpec.configuration.apidoc_title
end