rspec_api_documentation 1.1.0 → 2.0.0

Sign up to get free protection for your applications and to get access to all the features.
@@ -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: