dox 1.2.0 → 2.0.0.beta1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/lib/dox.rb CHANGED
@@ -27,7 +27,8 @@ require 'dox/formatters/xml'
27
27
  require 'dox/printers/base_printer'
28
28
  require 'dox/printers/action_printer'
29
29
  require 'dox/printers/document_printer'
30
- require 'dox/printers/example_printer'
30
+ require 'dox/printers/example_request_printer'
31
+ require 'dox/printers/example_response_printer'
31
32
  require 'dox/printers/resource_group_printer'
32
33
  require 'dox/printers/resource_printer'
33
34
  require 'dox/util/http'
@@ -48,4 +49,11 @@ module Dox
48
49
  def self.full_headers_whitelist
49
50
  (config.headers_whitelist.to_a + DEFAULT_HEADERS_WHITELIST).uniq
50
51
  end
52
+
53
+ RSpec.configure do |config|
54
+ config.after(:each, :dox) do |example|
55
+ example.metadata[:request] = request
56
+ example.metadata[:response] = response
57
+ end
58
+ end
51
59
  end
@@ -1,16 +1,49 @@
1
1
  module Dox
2
2
  class Config
3
- attr_reader :header_file_path, :desc_folder_path
3
+ attr_reader :schema_request_folder_path
4
+ attr_reader :schema_response_folder_path
5
+ attr_reader :schema_response_fail_file_path
4
6
  attr_accessor :headers_whitelist
7
+ attr_accessor :openapi_version
8
+ attr_accessor :api_version
9
+ attr_accessor :title
10
+ attr_accessor :description
11
+ attr_reader :descriptions_location
5
12
 
6
- def header_file_path=(file_path)
13
+ def descriptions_location=(folder_path)
14
+ raise(Errors::FolderNotFoundError, folder_path) unless Dir.exist?(folder_path)
15
+
16
+ @descriptions_location = folder_path
17
+ end
18
+
19
+ def schema_request_folder_path=(folder_path)
20
+ raise(Errors::FolderNotFoundError, folder_path) unless Dir.exist?(folder_path)
21
+
22
+ @schema_request_folder_path = folder_path
23
+ end
24
+
25
+ def schema_response_folder_path=(folder_path)
26
+ raise(Errors::FolderNotFoundError, folder_path) unless Dir.exist?(folder_path)
27
+
28
+ @schema_response_folder_path = folder_path
29
+ end
30
+
31
+ def schema_response_fail_file_path=(file_path)
7
32
  raise(Errors::FileNotFoundError, file_path) unless File.exist?(file_path)
8
- @header_file_path = file_path
33
+
34
+ @schema_response_fail_file_path = file_path
9
35
  end
10
36
 
11
37
  def desc_folder_path=(folder_path)
12
- raise(Errors::FolderNotFoundError, folder_path) unless Dir.exist?(folder_path)
13
- @desc_folder_path = folder_path
38
+ warn(
39
+ 'DEPRECATION WARNING: desc_folder_path will be removed in the next release, please use descriptions_location instead' # rubocop:disable Layout/LineLength
40
+ )
41
+
42
+ self.descriptions_location = folder_path
43
+ end
44
+
45
+ def header_file_path=(_file_path)
46
+ warn('WARNING: header_file_path is no longer used. Move header description to config.header_description.')
14
47
  end
15
48
  end
16
49
  end
@@ -8,6 +8,10 @@ module Dox
8
8
  attr_writer :path
9
9
  attr_writer :desc
10
10
  attr_writer :params
11
+ attr_writer :query_params
12
+ attr_writer :request_schema
13
+ attr_writer :response_schema_success
14
+ attr_writer :response_schema_fail
11
15
 
12
16
  def initialize(name, &block)
13
17
  self.name = name
@@ -17,13 +21,15 @@ module Dox
17
21
  end
18
22
 
19
23
  def config
20
- {
24
+ { action_request_schema: @request_schema.presence,
25
+ action_response_schema_success: @response_schema_success.presence,
26
+ action_response_schema_fail: @response_schema_fail.presence,
21
27
  action_name: @name.presence,
22
28
  action_verb: @verb.presence,
23
29
  action_path: @path.presence,
24
- action_desc: @desc.presence,
25
- action_params: @params
26
- }
30
+ action_desc: @desc.presence || '',
31
+ action_params: @params,
32
+ action_query_params: @query_params.presence || [] }
27
33
  end
28
34
  end
29
35
  end
@@ -14,6 +14,8 @@ module Dox
14
14
  self._resource = Resource.new(name, &block)
15
15
  end
16
16
 
17
+ alias tag resource
18
+
17
19
  def action(name, &block)
18
20
  self._action = Action.new(name, &block)
19
21
  end
@@ -22,6 +24,8 @@ module Dox
22
24
  self._group = ResourceGroup.new(name, &block)
23
25
  end
24
26
 
27
+ alias x_tag group
28
+
25
29
  def config
26
30
  {}.merge(_resource ? _resource.config : {})
27
31
  .merge(_action ? _action.config : {})
@@ -10,6 +10,7 @@ module Dox
10
10
 
11
11
  def const_missing(name)
12
12
  documentation = _subjects[infer_subject(name)]
13
+
13
14
  return super unless documentation
14
15
 
15
16
  Module.new do
@@ -1,16 +1,17 @@
1
1
  module Dox
2
2
  module Entities
3
3
  class Action
4
- attr_reader :name, :desc, :verb, :path, :uri_params
4
+ attr_reader :name, :desc, :verb, :path, :resource, :params
5
5
  attr_accessor :examples
6
6
 
7
- def initialize(name, details, request)
7
+ def initialize(details, request)
8
8
  @request = request
9
- @name = name
9
+ @name = details[:action_name]
10
+ @resource = details[:resource_name]
10
11
  @desc = details[:action_desc]
11
12
  @verb = details[:action_verb] || request.method
12
13
  @path = details[:action_path] || template_path
13
- @uri_params = details[:action_params] || template_path_params
14
+ @params = template_params(details[:action_params], details[:action_query_params] || [])
14
15
  @examples = []
15
16
 
16
17
  validate!
@@ -22,25 +23,44 @@ module Dox
22
23
 
23
24
  # /pokemons/1 => pokemons/{id}
24
25
  def template_path
25
- path = request.path.dup.presence || request.fullpath.split("?").first
26
+ path = request.path.dup.presence || request.fullpath.split('?').first
26
27
  path_params.each do |key, value|
27
28
  path.sub!(%r{\/#{value}(\/|$)}, "/{#{key}}\\1")
28
29
  end
30
+
29
31
  path
30
32
  end
31
33
 
34
+ def template_params(defined_params, query_params)
35
+ acquire_path_params + acquire_defined_params(defined_params) + query_params
36
+ end
37
+
32
38
  def path_params
33
- @path_params ||=
34
- request.path_parameters.symbolize_keys.except(:action, :controller, :format, :subdomain)
39
+ request.path_parameters.symbolize_keys.except(:action, :controller, :format, :subdomain)
40
+ end
41
+
42
+ def acquire_path_params
43
+ return [] if path_params.nil?
44
+
45
+ path_params.map do |param, value|
46
+ { name: param,
47
+ in: :path,
48
+ schema: { type: guess_param_type(value) },
49
+ example: value }
50
+ end
35
51
  end
36
52
 
37
- def template_path_params
38
- h = {}
39
- path_params.each do |param, value|
40
- param_type = guess_param_type(value)
41
- h[param] = { type: param_type, required: :required, value: value }
53
+ def acquire_defined_params(defined_params)
54
+ return [] if defined_params.nil?
55
+
56
+ defined_params.map do |key, value|
57
+ { name: key,
58
+ in: 'query',
59
+ required: value[:required],
60
+ example: value[:value],
61
+ description: value[:description].presence || '',
62
+ schema: { type: value[:type] } }
42
63
  end
43
- h
44
64
  end
45
65
 
46
66
  def guess_param_type(param)
@@ -3,6 +3,8 @@ module Dox
3
3
  class Example
4
4
  extend Forwardable
5
5
 
6
+ attr_reader :desc, :name, :request_schema, :response_schema_success, :response_schema_fail
7
+
6
8
  def_delegator :response, :status, :response_status
7
9
  def_delegator :response, :content_type, :response_content_type
8
10
  def_delegator :request, :content_type, :request_content_type
@@ -10,6 +12,10 @@ module Dox
10
12
 
11
13
  def initialize(details, request, response)
12
14
  @desc = details[:description]
15
+ @name = details[:resource_name].downcase
16
+ @request_schema = details[:action_request_schema]
17
+ @response_schema_success = details[:action_response_schema_success]
18
+ @response_schema_fail = details[:action_response_schema_fail]
13
19
  @request = request
14
20
  @response = response
15
21
  end
@@ -34,6 +40,10 @@ module Dox
34
40
  @request_headers ||= filter_headers(request)
35
41
  end
36
42
 
43
+ def response_success?
44
+ response.successful?
45
+ end
46
+
37
47
  # Rails 4 includes the body params in the request_fullpath
38
48
  def request_fullpath
39
49
  if request.query_parameters.present?
@@ -67,7 +77,7 @@ module Dox
67
77
  request.path.presence || request.fullpath.split('?')[0]
68
78
  end
69
79
 
70
- attr_reader :desc, :request, :response
80
+ attr_reader :request, :response
71
81
 
72
82
  def filter_headers(obj)
73
83
  headers_whitelist.map do |header|
@@ -1,17 +1,16 @@
1
1
  module Dox
2
2
  module Entities
3
3
  class Resource
4
-
5
- attr_reader :name, :desc, :endpoint
4
+ attr_reader :name, :desc, :endpoint, :group
6
5
  attr_accessor :actions
7
6
 
8
- def initialize(name, details)
9
- @name = name
7
+ def initialize(details)
8
+ @name = details[:resource_name]
9
+ @group = details[:resource_group_name]
10
10
  @desc = details[:resource_desc]
11
11
  @endpoint = details[:resource_endpoint]
12
12
  @actions = {}
13
13
  end
14
-
15
14
  end
16
15
  end
17
16
  end
@@ -1,12 +1,11 @@
1
1
  module Dox
2
2
  module Entities
3
3
  class ResourceGroup
4
-
5
4
  attr_reader :name
6
5
  attr_accessor :desc, :resources
7
6
 
8
- def initialize(name, details)
9
- @name = name
7
+ def initialize(details)
8
+ @name = details[:resource_group_name]
10
9
  @desc = details[:resource_group_desc]
11
10
  @resources = {}
12
11
  end
@@ -20,7 +20,7 @@ module Dox
20
20
 
21
21
  def stop(notification)
22
22
  if notification.failed_examples.any?
23
- $stderr.puts(notification.fully_formatted_failed_examples)
23
+ warn(notification.fully_formatted_failed_examples)
24
24
  else
25
25
  printer.print(passed_examples)
26
26
  end
@@ -28,7 +28,8 @@ module Dox
28
28
 
29
29
  def dump_summary(summary)
30
30
  return if summary.failed_examples.none?
31
- $stderr.puts(summary.fully_formatted)
31
+
32
+ warn(summary.fully_formatted)
32
33
  exit(-1)
33
34
  end
34
35
 
@@ -44,28 +45,26 @@ module Dox
44
45
  if group
45
46
  group.tap { |g| g.desc ||= current_example.resource_group_desc }
46
47
  else
47
- passed_examples[group_name] = Entities::ResourceGroup.new(group_name,
48
- current_example.metadata)
48
+ passed_examples[group_name] = Entities::ResourceGroup.new(current_example.metadata)
49
49
  end
50
50
  end
51
51
 
52
52
  def load_or_save_resource_to_group(group)
53
- resource_name = current_example.resource_name
54
- group.resources[resource_name] ||= Entities::Resource.new(resource_name,
55
- current_example.metadata)
53
+ group.resources[current_example.resource_name] ||= Entities::Resource.new(current_example.metadata)
56
54
  end
57
55
 
58
56
  def load_or_save_action_to_resource(resource)
59
- action_name = current_example.action_name
60
- resource.actions[action_name] ||= Entities::Action.new(action_name, current_example.metadata,
61
- current_example.request)
57
+ resource.actions[current_example.action_name] ||= Entities::Action.new(current_example.metadata,
58
+ current_example.request)
62
59
  end
63
60
 
64
61
  def move_example_to_passed
65
62
  group = load_or_save_group
66
63
  resource = load_or_save_resource_to_group(group)
67
64
  action = load_or_save_action_to_resource(resource)
68
- action.examples << Entities::Example.new(current_example.metadata, current_example.request, current_example.response)
65
+ action.examples << Entities::Example.new(current_example.metadata,
66
+ current_example.request,
67
+ current_example.response)
69
68
  end
70
69
 
71
70
  def printer
@@ -3,44 +3,35 @@ module Dox
3
3
  class ActionPrinter < BasePrinter
4
4
  def print(action)
5
5
  self.action = action
6
- @output.puts action_title
7
- @output.puts action_uri_params if action.uri_params.present?
6
+ @action_hash = find_or_add(find_or_add(spec, action.path.to_s), action.verb.downcase.to_sym)
8
7
 
9
- action.examples.each do |example|
10
- example_printer.print(example)
11
- end
8
+ add_action
9
+ add_action_params
10
+
11
+ print_examples
12
12
  end
13
13
 
14
14
  private
15
15
 
16
- attr_accessor :action
17
-
18
- def action_title
19
- <<-HEREDOC
16
+ attr_accessor :action, :action_hash
20
17
 
21
- ### #{action.name} [#{action.verb.upcase} #{action.path}]
22
- #{print_desc(action.desc)}
23
- HEREDOC
18
+ def add_action
19
+ action_hash['summary'] = action.name
20
+ action_hash['tags'] = [action.resource]
21
+ action_hash['description'] = format_desc(action.desc)
24
22
  end
25
23
 
26
- def action_uri_params
27
- <<-HEREDOC
28
- + Parameters
29
- #{formatted_params(action.uri_params)}
30
- HEREDOC
31
- end
24
+ def add_action_params
25
+ return unless action.params.present?
32
26
 
33
- def example_printer
34
- @example_printer ||= ExamplePrinter.new(@output)
27
+ action_hash['parameters'] = action.params
35
28
  end
36
29
 
37
- def formatted_params(uri_params)
38
- uri_params.map do |param, details|
39
- desc = " + #{CGI.escape(param.to_s)}: `#{CGI.escape(details[:value].to_s)}` (#{details[:type]}, #{details[:required]})"
40
- desc += " - #{details[:description]}" if details[:description].present?
41
- desc += "\n + Default: #{details[:default]}" if details[:default].present?
42
- desc
43
- end.flatten.join("\n")
30
+ def print_examples
31
+ action.examples.each do |example|
32
+ ExampleRequestPrinter.new(action_hash).print(example)
33
+ ExampleResponsePrinter.new(action_hash).print(example)
34
+ end
44
35
  end
45
36
  end
46
37
  end
@@ -1,37 +1,56 @@
1
+ require 'rexml/document'
2
+
1
3
  module Dox
2
4
  module Printers
3
5
  class BasePrinter
4
- def initialize(output)
5
- @output = output
6
+ attr_reader :spec
7
+
8
+ def initialize(spec)
9
+ @spec = spec || {}
6
10
  end
7
11
 
8
12
  def print
9
13
  raise NotImplementedError
10
14
  end
11
15
 
12
- private
16
+ def find_or_add(hash, key, default = {})
17
+ return hash[key] if hash.key?(key)
13
18
 
14
- def descriptions_folder_path
15
- Dox.config.desc_folder_path
19
+ hash[key] = default
16
20
  end
17
21
 
18
- def print_desc(desc, fullpath = false)
19
- return if desc.blank?
22
+ def read_file(path, root_path: Dox.config.descriptions_location)
23
+ return '' unless root_path
24
+
25
+ File.read(File.join(root_path, path))
26
+ end
20
27
 
21
- if desc.to_s =~ /.*\.md$/
22
- path = if fullpath
23
- desc
24
- else
25
- descriptions_folder_path.join(desc).to_s
26
- end
27
- content(path)
28
+ def formatted_body(body_str, content_type)
29
+ case content_type
30
+ when %r{application\/.*json}
31
+ JSON.parse(body_str)
32
+ when /xml/
33
+ pretty_xml(body_str)
28
34
  else
29
- desc
35
+ body_str
30
36
  end
31
37
  end
32
38
 
33
- def content(path)
34
- File.read(path)
39
+ def pretty_xml(xml_string)
40
+ doc = REXML::Document.new(xml_string)
41
+ formatter = REXML::Formatters::Pretty.new
42
+ formatter.compact = true
43
+ result = ''
44
+ formatter.write(doc, result)
45
+ result
46
+ end
47
+
48
+ def format_desc(description)
49
+ desc = description
50
+ desc = '' if desc.nil?
51
+ desc = read_file(desc) if desc.end_with?('.md')
52
+
53
+ desc
35
54
  end
36
55
  end
37
56
  end