diff --git a/lib/rspec_api_documentation/dsl/resource.rb b/lib/rspec_api_documentation/dsl/resource.rb index 3d92a4b2..03a2210f 100644 --- a/lib/rspec_api_documentation/dsl/resource.rb +++ b/lib/rspec_api_documentation/dsl/resource.rb @@ -50,6 +50,10 @@ def header(name, value) headers[name] = value end + def explanation(text) + safe_metadata(:resource_explanation, text) + end + private def safe_metadata(field, default) diff --git a/lib/rspec_api_documentation/example.rb b/lib/rspec_api_documentation/example.rb index 73264b43..73822d45 100644 --- a/lib/rspec_api_documentation/example.rb +++ b/lib/rspec_api_documentation/example.rb @@ -42,6 +42,10 @@ def has_response_fields? respond_to?(:response_fields) && response_fields.present? end + def resource_explanation + metadata[:resource_explanation] || nil + end + def explanation metadata[:explanation] || nil end diff --git a/lib/rspec_api_documentation/writers/index_helper.rb b/lib/rspec_api_documentation/writers/index_helper.rb index b52b26b4..c72d41fe 100644 --- a/lib/rspec_api_documentation/writers/index_helper.rb +++ b/lib/rspec_api_documentation/writers/index_helper.rb @@ -6,7 +6,7 @@ module IndexHelper def sections(examples, configuration) resources = examples.group_by(&:resource_name).inject([]) do |arr, (resource_name, examples)| ordered_examples = configuration.keep_source_order ? examples : examples.sort_by(&:description) - arr.push(:resource_name => resource_name, :examples => ordered_examples) + arr.push(:resource_name => resource_name, :examples => ordered_examples, :resource_explanation => examples.first.metadata[:resource_explanation]) end configuration.keep_source_order ? resources : resources.sort_by { |resource| resource[:resource_name] } end diff --git a/lib/rspec_api_documentation/writers/json_writer.rb b/lib/rspec_api_documentation/writers/json_writer.rb index 6c956083..8ae5c4b9 100644 --- a/lib/rspec_api_documentation/writers/json_writer.rb +++ b/lib/rspec_api_documentation/writers/json_writer.rb @@ -47,6 +47,7 @@ def as_json(opts = nil) def section_hash(section) { :name => section[:resource_name], + :explanation => section[:resource_explanation], :examples => section[:examples].map { |example| { :description => example.description, @@ -85,6 +86,7 @@ def filename def as_json(opts = nil) { :resource => resource_name, + :resource_explanation => resource_explanation, :http_method => http_method, :route => route, :description => description, diff --git a/templates/rspec_api_documentation/html_example.mustache b/templates/rspec_api_documentation/html_example.mustache index 5e8385c3..55fca51e 100644 --- a/templates/rspec_api_documentation/html_example.mustache +++ b/templates/rspec_api_documentation/html_example.mustache @@ -10,6 +10,11 @@

{{resource_name}} API

+ {{# resource_explanation }} +

+ {{{ resource_explanation }}} +

+ {{/ resource_explanation }}

{{ description }}

diff --git a/templates/rspec_api_documentation/html_index.mustache b/templates/rspec_api_documentation/html_index.mustache index 3df2c6aa..20332576 100644 --- a/templates/rspec_api_documentation/html_index.mustache +++ b/templates/rspec_api_documentation/html_index.mustache @@ -14,6 +14,11 @@ {{# sections }}

{{ resource_name }}

+ {{# resource_explanation }} +

+ {{{ resource_explanation }}} +

+ {{/ resource_explanation }}
    {{# examples }} diff --git a/templates/rspec_api_documentation/markdown_example.mustache b/templates/rspec_api_documentation/markdown_example.mustache index 1183f707..bf2dc764 100644 --- a/templates/rspec_api_documentation/markdown_example.mustache +++ b/templates/rspec_api_documentation/markdown_example.mustache @@ -1,4 +1,8 @@ # {{ resource_name }} API +{{# resource_explanation }} + +{{ resource_explanation }} +{{/ resource_explanation }} ## {{ description }} diff --git a/templates/rspec_api_documentation/markdown_index.mustache b/templates/rspec_api_documentation/markdown_index.mustache index bdd11f55..7dcebc19 100644 --- a/templates/rspec_api_documentation/markdown_index.mustache +++ b/templates/rspec_api_documentation/markdown_index.mustache @@ -2,6 +2,10 @@ {{# sections }} ## {{ resource_name }} +{{# resource_explanation }} + +{{ resource_explanation }} +{{/ resource_explanation }} {{# examples }} * [{{ description }}]({{ dirname }}/{{ filename }}) diff --git a/templates/rspec_api_documentation/textile_example.mustache b/templates/rspec_api_documentation/textile_example.mustache index e32917ba..45c28fa3 100644 --- a/templates/rspec_api_documentation/textile_example.mustache +++ b/templates/rspec_api_documentation/textile_example.mustache @@ -1,5 +1,9 @@ h1. {{ resource_name }} API +{{# resource_explanation }} +{{ resource_explanation }} + +{{/ resource_explanation }} h2. {{ description }} h3. {{ http_method }} {{ route }} diff --git a/templates/rspec_api_documentation/textile_index.mustache b/templates/rspec_api_documentation/textile_index.mustache index cbb93d57..bd755d61 100644 --- a/templates/rspec_api_documentation/textile_index.mustache +++ b/templates/rspec_api_documentation/textile_index.mustache @@ -3,6 +3,10 @@ h1. {{ api_name }} {{# sections }} h2. {{ resource_name }} +{{# resource_explanation }} +{{ resource_explanation }} + +{{/ resource_explanation }} {{# examples }} * "{{ description }}":{{ dirname }}/{{ filename }} {{/ examples }}