rspec_api_documentation 1.1.0 → 2.0.0

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.
@@ -28,7 +28,9 @@ module RspecApiDocumentation
28
28
  module Writers
29
29
  extend ActiveSupport::Autoload
30
30
 
31
+ autoload :GeneralMarkupWriter
31
32
  autoload :HtmlWriter
33
+ autoload :TextileWriter
32
34
  autoload :JsonWriter
33
35
  autoload :JsonIodocsWriter
34
36
  autoload :IndexWriter
@@ -36,6 +38,17 @@ module RspecApiDocumentation
36
38
  autoload :CombinedJsonWriter
37
39
  end
38
40
 
41
+ module Views
42
+ extend ActiveSupport::Autoload
43
+
44
+ autoload :MarkupIndex
45
+ autoload :MarkupExample
46
+ autoload :HtmlIndex
47
+ autoload :HtmlExample
48
+ autoload :TextileIndex
49
+ autoload :TextileExample
50
+ end
51
+
39
52
  def self.configuration
40
53
  @configuration ||= Configuration.new
41
54
  end
@@ -57,6 +57,20 @@ module RspecApiDocumentation
57
57
  add_setting :curl_host, :default => nil
58
58
  add_setting :keep_source_order, :default => false
59
59
  add_setting :api_name, :default => "API Documentation"
60
+ add_setting :io_docs_protocol, :default => "http"
61
+
62
+ def client_method=(new_client_method)
63
+ RspecApiDocumentation::DSL::Resource.module_eval <<-RUBY
64
+ alias :#{new_client_method} #{client_method}
65
+ undef #{client_method}
66
+ RUBY
67
+
68
+ @client_method = new_client_method
69
+ end
70
+
71
+ def client_method
72
+ @client_method ||= :client
73
+ end
60
74
 
61
75
  def settings
62
76
  @settings ||= {}
@@ -7,7 +7,7 @@ module RspecApiDocumentation::DSL
7
7
  extend ActiveSupport::Concern
8
8
  include Rack::Test::Utils
9
9
 
10
- delegate :response_headers, :status, :response_status, :response_body, :to => :client
10
+ delegate :response_headers, :status, :response_status, :response_body, :to => :rspec_api_documentation_client
11
11
 
12
12
  module ClassMethods
13
13
  def example_request(description, params = {}, &block)
@@ -44,7 +44,7 @@ module RspecApiDocumentation::DSL
44
44
  params_or_body = respond_to?(:raw_post) ? raw_post : params
45
45
  end
46
46
 
47
- client.send(method, path_or_query, params_or_body, headers)
47
+ rspec_api_documentation_client.send(method, path_or_query, params_or_body, headers)
48
48
  end
49
49
 
50
50
  def query_string
@@ -52,14 +52,18 @@ module RspecApiDocumentation::DSL
52
52
  end
53
53
 
54
54
  def params
55
- return unless example.metadata[:parameters]
56
- parameters = example.metadata[:parameters].inject({}) do |hash, param|
55
+ parameters = example.metadata.fetch(:parameters, {}).inject({}) do |hash, param|
57
56
  set_param(hash, param)
58
57
  end
59
58
  parameters.merge!(extra_params)
60
59
  parameters
61
60
  end
62
61
 
62
+ def header(name, value)
63
+ example.metadata[:headers] ||= {}
64
+ example.metadata[:headers][name] = value
65
+ end
66
+
63
67
  def headers
64
68
  return unless example.metadata[:headers]
65
69
  example.metadata[:headers].inject({}) do |hash, (header, value)|
@@ -101,6 +105,11 @@ module RspecApiDocumentation::DSL
101
105
  end
102
106
 
103
107
  private
108
+
109
+ def rspec_api_documentation_client
110
+ send(RspecApiDocumentation.configuration.client_method)
111
+ end
112
+
104
113
  def extra_params
105
114
  return {} if @extra_params.nil?
106
115
  @extra_params.inject({}) do |h, (k, v)|
@@ -41,33 +41,6 @@ module RspecApiDocumentation::DSL
41
41
  headers[name] = value
42
42
  end
43
43
 
44
- def required_parameters(*names)
45
- warn "required_parameters is no longer supported. Please use parameter :name, '', :required => true instead."
46
-
47
- names.each do |name|
48
- param = parameters.find { |param| param[:name] == name.to_s }
49
- raise "Undefined parameters can not be required." unless param
50
- param[:required] = true
51
- end
52
- end
53
-
54
- def scope_parameters(scope, keys)
55
- warn "scope_paramters is no longer supported. Please use parameter :name, '', :scope => 'scope' instead."
56
-
57
- return unless metadata[:parameters]
58
-
59
- if keys == :all
60
- keys = parameter_keys.map(&:to_s)
61
- else
62
- keys = keys.map(&:to_s)
63
- end
64
-
65
- keys.each do |key|
66
- param = parameters.detect { |param| param[:name] == key }
67
- param[:scope] = scope if param
68
- end
69
- end
70
-
71
44
  private
72
45
  def parameters
73
46
  metadata[:parameters] ||= []
@@ -0,0 +1,16 @@
1
+ module RspecApiDocumentation
2
+ module Views
3
+ class HtmlExample < MarkupExample
4
+ EXTENSION = 'html'
5
+
6
+ def initialize(example, configuration)
7
+ super
8
+ self.template_name = "rspec_api_documentation/html_example"
9
+ end
10
+
11
+ def extension
12
+ EXTENSION
13
+ end
14
+ end
15
+ end
16
+ end
@@ -0,0 +1,14 @@
1
+ module RspecApiDocumentation
2
+ module Views
3
+ class HtmlIndex < MarkupIndex
4
+ def initialize(index, configuration)
5
+ super
6
+ self.template_name = "rspec_api_documentation/html_index"
7
+ end
8
+
9
+ def examples
10
+ @index.examples.map { |example| HtmlExample.new(example, @configuration) }
11
+ end
12
+ end
13
+ end
14
+ end
@@ -0,0 +1,58 @@
1
+ require 'mustache'
2
+
3
+ module RspecApiDocumentation
4
+ module Views
5
+ class MarkupExample < Mustache
6
+ def initialize(example, configuration)
7
+ @example = example
8
+ @host = configuration.curl_host
9
+ self.template_path = configuration.template_path
10
+ end
11
+
12
+ def method_missing(method, *args, &block)
13
+ @example.send(method, *args, &block)
14
+ end
15
+
16
+ def respond_to?(method, include_private = false)
17
+ super || @example.respond_to?(method, include_private)
18
+ end
19
+
20
+ def dirname
21
+ resource_name.downcase.gsub(/\s+/, '_')
22
+ end
23
+
24
+ def filename
25
+ basename = description.downcase.gsub(/\s+/, '_').gsub(/[^a-z_]/, '')
26
+ basename = Digest::MD5.new.update(description).to_s if basename.blank?
27
+ "#{basename}.#{extension}"
28
+ end
29
+
30
+ def requests
31
+ super.map do |hash|
32
+ hash[:request_headers_text] = format_hash(hash[:request_headers])
33
+ hash[:request_query_parameters_text] = format_hash(hash[:request_query_parameters])
34
+ hash[:response_headers_text] = format_hash(hash[:response_headers])
35
+ if @host
36
+ hash[:curl] = hash[:curl].output(@host) if hash[:curl].is_a? RspecApiDocumentation::Curl
37
+ else
38
+ hash[:curl] = nil
39
+ end
40
+ hash
41
+ end
42
+ end
43
+
44
+ def extension
45
+ raise 'Parent class. This method should not be called.'
46
+ end
47
+
48
+ private
49
+
50
+ def format_hash(hash = {})
51
+ return nil unless hash.present?
52
+ hash.collect do |k, v|
53
+ "#{k}: #{v}"
54
+ end.join("\n")
55
+ end
56
+ end
57
+ end
58
+ end
@@ -0,0 +1,21 @@
1
+ require 'mustache'
2
+
3
+ module RspecApiDocumentation
4
+ module Views
5
+ class MarkupIndex < Mustache
6
+ def initialize(index, configuration)
7
+ @index = index
8
+ @configuration = configuration
9
+ self.template_path = configuration.template_path
10
+ end
11
+
12
+ def api_name
13
+ @configuration.api_name
14
+ end
15
+
16
+ def sections
17
+ RspecApiDocumentation::Writers::IndexWriter.sections(examples, @configuration)
18
+ end
19
+ end
20
+ end
21
+ end
@@ -0,0 +1,16 @@
1
+ module RspecApiDocumentation
2
+ module Views
3
+ class TextileExample < MarkupExample
4
+ EXTENSION = 'textile'
5
+
6
+ def initialize(example, configuration)
7
+ super
8
+ self.template_name = "rspec_api_documentation/textile_example"
9
+ end
10
+
11
+ def extension
12
+ EXTENSION
13
+ end
14
+ end
15
+ end
16
+ end
@@ -0,0 +1,14 @@
1
+ module RspecApiDocumentation
2
+ module Views
3
+ class TextileIndex < MarkupIndex
4
+ def initialize(index, configuration)
5
+ super
6
+ self.template_name = "rspec_api_documentation/textile_index"
7
+ end
8
+
9
+ def examples
10
+ @index.examples.map { |example| TextileExample.new(example, @configuration) }
11
+ end
12
+ end
13
+ end
14
+ end
@@ -0,0 +1,42 @@
1
+ module RspecApiDocumentation
2
+ module Writers
3
+ class GeneralMarkupWriter
4
+ attr_accessor :index, :configuration
5
+
6
+ INDEX_FILE_NAME = 'index'
7
+
8
+ def initialize(index, configuration)
9
+ self.index = index
10
+ self.configuration = configuration
11
+ end
12
+
13
+ def self.write(index, configuration)
14
+ writer = new(index, configuration)
15
+ writer.write
16
+ end
17
+
18
+ def write
19
+ File.open(configuration.docs_dir.join(index_file_name + '.' + extension), "w+") do |f|
20
+ f.write markup_index_class.new(index, configuration).render
21
+ end
22
+
23
+ index.examples.each do |example|
24
+ markup_example = markup_example_class.new(example, configuration)
25
+ FileUtils.mkdir_p(configuration.docs_dir.join(markup_example.dirname))
26
+
27
+ File.open(configuration.docs_dir.join(markup_example.dirname, markup_example.filename), "w+") do |f|
28
+ f.write markup_example.render
29
+ end
30
+ end
31
+ end
32
+
33
+ def index_file_name
34
+ INDEX_FILE_NAME
35
+ end
36
+
37
+ def extension
38
+ raise 'Parent class. This method should not be called.'
39
+ end
40
+ end
41
+ end
42
+ end
@@ -1,101 +1,20 @@
1
- require 'mustache'
2
-
3
1
  module RspecApiDocumentation
4
2
  module Writers
5
- class HtmlWriter
3
+ class HtmlWriter < GeneralMarkupWriter
6
4
  attr_accessor :index, :configuration
7
5
 
8
- def initialize(index, configuration)
9
- self.index = index
10
- self.configuration = configuration
11
- end
12
-
13
- def self.write(index, configuration)
14
- writer = new(index, configuration)
15
- writer.write
16
- end
17
-
18
- def write
19
- File.open(configuration.docs_dir.join("index.html"), "w+") do |f|
20
- f.write HtmlIndex.new(index, configuration).render
21
- end
22
- index.examples.each do |example|
23
- html_example = HtmlExample.new(example, configuration)
24
- FileUtils.mkdir_p(configuration.docs_dir.join(html_example.dirname))
25
- File.open(configuration.docs_dir.join(html_example.dirname, html_example.filename), "w+") do |f|
26
- f.write html_example.render
27
- end
28
- end
29
- end
30
- end
31
-
32
- class HtmlIndex < Mustache
33
- def initialize(index, configuration)
34
- @index = index
35
- @configuration = configuration
36
- self.template_path = configuration.template_path
37
- self.template_name = "rspec_api_documentation/html_index"
38
- end
39
-
40
- def api_name
41
- @configuration.api_name
42
- end
43
-
44
- def sections
45
- IndexWriter.sections(examples, @configuration)
46
- end
47
-
48
- def examples
49
- @index.examples.map { |example| HtmlExample.new(example, @configuration) }
50
- end
51
- end
52
-
53
- class HtmlExample < Mustache
54
- def initialize(example, configuration)
55
- @example = example
56
- @host = configuration.curl_host
57
- self.template_path = configuration.template_path
58
- self.template_name = "rspec_api_documentation/html_example"
59
- end
60
-
61
- def method_missing(method, *args, &block)
62
- @example.send(method, *args, &block)
63
- end
64
-
65
- def respond_to?(method, include_private = false)
66
- super || @example.respond_to?(method, include_private)
67
- end
68
-
69
- def dirname
70
- resource_name.downcase.gsub(/\s+/, '_')
71
- end
6
+ EXTENSION = 'html'
72
7
 
73
- def filename
74
- basename = description.downcase.gsub(/\s+/, '_').gsub(/[^a-z_]/, '')
75
- basename = Digest::MD5.new.update(description).to_s if basename.blank?
76
- "#{basename}.html"
8
+ def markup_index_class
9
+ RspecApiDocumentation::Views::HtmlIndex
77
10
  end
78
11
 
79
- def requests
80
- super.map do |hash|
81
- hash[:request_headers_text] = format_hash(hash[:request_headers])
82
- hash[:request_query_parameters_text] = format_hash(hash[:request_query_parameters])
83
- hash[:response_headers_text] = format_hash(hash[:response_headers])
84
- if @host
85
- hash[:curl] = hash[:curl].output(@host) if hash[:curl].is_a? RspecApiDocumentation::Curl
86
- else
87
- hash[:curl] = nil
88
- end
89
- hash
90
- end
12
+ def markup_example_class
13
+ RspecApiDocumentation::Views::HtmlExample
91
14
  end
92
15
 
93
- private
94
- def format_hash(hash = {})
95
- return nil unless hash.present?
96
- hash.collect do |k, v|
97
- "#{k}: #{v}"
98
- end.join("\n")
16
+ def extension
17
+ EXTENSION
99
18
  end
100
19
  end
101
20
  end
@@ -100,7 +100,7 @@ module RspecApiDocumentation
100
100
  {
101
101
  @api_key.to_sym => {
102
102
  :name => @configuration.api_name,
103
- :protocol => "http",
103
+ :protocol => @configuration.io_docs_protocol,
104
104
  :publicPath => "",
105
105
  :baseURL => @configuration.curl_host
106
106
  }
@@ -0,0 +1,21 @@
1
+ module RspecApiDocumentation
2
+ module Writers
3
+ class TextileWriter < GeneralMarkupWriter
4
+ attr_accessor :index, :configuration
5
+
6
+ EXTENSION = 'textile'
7
+
8
+ def markup_index_class
9
+ RspecApiDocumentation::Views::TextileIndex
10
+ end
11
+
12
+ def markup_example_class
13
+ RspecApiDocumentation::Views::TextileExample
14
+ end
15
+
16
+ def extension
17
+ EXTENSION
18
+ end
19
+ end
20
+ end
21
+ end
@@ -0,0 +1,68 @@
1
+ h1. {{ resource_name }} API
2
+
3
+ h2. {{ description }}
4
+
5
+ h3. {{ http_method }} {{ route }}
6
+
7
+ {{# explanation }}
8
+ {{ explanation }}
9
+ {{/ explanation }}
10
+
11
+ {{# has_parameters? }}
12
+ h3. Parameters
13
+ {{# parameters }}
14
+
15
+ Name : {{ name }} {{# required }} *- required -*{{/ required }}
16
+ Description : {{ description }}
17
+ {{/ parameters }}
18
+ {{/ has_parameters? }}
19
+
20
+ {{# requests }}
21
+ h3. Request
22
+
23
+ h4. Headers
24
+
25
+ <pre>{{ request_headers_text }}</pre>
26
+
27
+ h4. Route
28
+
29
+ <pre>{{ request_method }} {{ request_path }}</pre>
30
+
31
+ {{# request_query_parameters_text }}
32
+ h4. Query Parameters
33
+
34
+ <pre>{{ request_query_parameters_text }}</pre>
35
+ {{/ request_query_parameters_text }}
36
+
37
+ {{# request_body }}
38
+ h4. Body
39
+
40
+ <pre>{{{ request_body }}}</pre>
41
+ {{/ request_body }}
42
+
43
+ {{# curl }}
44
+ h4. cURL
45
+
46
+ <pre class="request">{{ curl }}</pre>
47
+ {{/ curl }}
48
+
49
+ {{# response_status }}
50
+ h3. Response
51
+
52
+ h4. Headers
53
+
54
+ <pre>{{ response_headers_text }}</pre>
55
+
56
+ h4. Status
57
+
58
+ <pre>{{ response_status }} {{ response_status_text}}</pre>
59
+
60
+ {{# response_body }}
61
+ h4. Body
62
+
63
+ <pre>{{{ response_body }}}</pre>
64
+ {{/ response_body }}
65
+ {{/ response_status }}
66
+
67
+ {{/ requests }}
68
+
@@ -0,0 +1,10 @@
1
+ h1. {{ api_name }}
2
+
3
+ {{# sections }}
4
+ h2. {{ resource_name }}
5
+
6
+ {{# examples }}
7
+ * "{{ description }}":{{ dirname }}/{{ filename }}
8
+ {{/ examples }}
9
+
10
+ {{/ sections }}
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: rspec_api_documentation
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.1.0
4
+ version: 2.0.0
5
5
  prerelease:
6
6
  platform: ruby
7
7
  authors:
@@ -11,7 +11,7 @@ authors:
11
11
  autorequire:
12
12
  bindir: bin
13
13
  cert_chain: []
14
- date: 2013-08-12 00:00:00.000000000 Z
14
+ date: 2013-10-14 00:00:00.000000000 Z
15
15
  dependencies:
16
16
  - !ruby/object:Gem::Dependency
17
17
  name: rspec
@@ -230,33 +230,43 @@ executables: []
230
230
  extensions: []
231
231
  extra_rdoc_files: []
232
232
  files:
233
- - lib/rspec_api_documentation/api_documentation.rb
233
+ - lib/rspec_api_documentation.rb
234
+ - lib/tasks/docs.rake
235
+ - lib/rspec_api_documentation/rack_test_client.rb
234
236
  - lib/rspec_api_documentation/api_formatter.rb
235
- - lib/rspec_api_documentation/client_base.rb
236
- - lib/rspec_api_documentation/configuration.rb
237
237
  - lib/rspec_api_documentation/curl.rb
238
+ - lib/rspec_api_documentation/index.rb
239
+ - lib/rspec_api_documentation/headers.rb
240
+ - lib/rspec_api_documentation/oauth2_mac_client.rb
238
241
  - lib/rspec_api_documentation/dsl/callback.rb
239
242
  - lib/rspec_api_documentation/dsl/endpoint.rb
240
243
  - lib/rspec_api_documentation/dsl/resource.rb
241
244
  - lib/rspec_api_documentation/dsl.rb
242
- - lib/rspec_api_documentation/example.rb
243
- - lib/rspec_api_documentation/headers.rb
244
- - lib/rspec_api_documentation/index.rb
245
- - lib/rspec_api_documentation/oauth2_mac_client.rb
246
- - lib/rspec_api_documentation/rack_test_client.rb
247
- - lib/rspec_api_documentation/railtie.rb
248
- - lib/rspec_api_documentation/test_server.rb
249
- - lib/rspec_api_documentation/writers/combined_json_writer.rb
250
- - lib/rspec_api_documentation/writers/combined_text_writer.rb
251
- - lib/rspec_api_documentation/writers/formatter.rb
245
+ - lib/rspec_api_documentation/views/html_example.rb
246
+ - lib/rspec_api_documentation/views/html_index.rb
247
+ - lib/rspec_api_documentation/views/textile_example.rb
248
+ - lib/rspec_api_documentation/views/textile_index.rb
249
+ - lib/rspec_api_documentation/views/markup_index.rb
250
+ - lib/rspec_api_documentation/views/markup_example.rb
251
+ - lib/rspec_api_documentation/writers/textile_writer.rb
252
+ - lib/rspec_api_documentation/writers/general_markup_writer.rb
252
253
  - lib/rspec_api_documentation/writers/html_writer.rb
253
- - lib/rspec_api_documentation/writers/index_writer.rb
254
254
  - lib/rspec_api_documentation/writers/json_iodocs_writer.rb
255
255
  - lib/rspec_api_documentation/writers/json_writer.rb
256
- - lib/rspec_api_documentation.rb
257
- - lib/tasks/docs.rake
258
- - templates/rspec_api_documentation/html_example.mustache
256
+ - lib/rspec_api_documentation/writers/combined_json_writer.rb
257
+ - lib/rspec_api_documentation/writers/formatter.rb
258
+ - lib/rspec_api_documentation/writers/index_writer.rb
259
+ - lib/rspec_api_documentation/writers/combined_text_writer.rb
260
+ - lib/rspec_api_documentation/configuration.rb
261
+ - lib/rspec_api_documentation/example.rb
262
+ - lib/rspec_api_documentation/api_documentation.rb
263
+ - lib/rspec_api_documentation/test_server.rb
264
+ - lib/rspec_api_documentation/railtie.rb
265
+ - lib/rspec_api_documentation/client_base.rb
266
+ - templates/rspec_api_documentation/textile_example.mustache
259
267
  - templates/rspec_api_documentation/html_index.mustache
268
+ - templates/rspec_api_documentation/textile_index.mustache
269
+ - templates/rspec_api_documentation/html_example.mustache
260
270
  homepage: http://smartlogicsolutions.com
261
271
  licenses: []
262
272
  post_install_message: