Add common api description before resources sections (closes #354)

README.md

@@ -118,6 +118,9 @@ RspecApiDocumentation.configure do |config|
 
   # Change the name of the API on index pages
   config.api_name = "API Documentation"
+
+  # Change the description of the API on index pages
+  config.api_explanation = "API Description"
 
   # Redefine what method the DSL thinks is the client
   # This is useful if you need to `let` your own client, most likely a model.

example/spec/acceptance_helper.rb

@@ -6,4 +6,5 @@
   config.format = [:json, :combined_text, :html]
   config.curl_host = 'http://localhost:3000'
   config.api_name = "Example App API"
+  config.api_explanation = "API Example Description"
 end

features/api_blueprint_documentation.feature

@@ -64,6 +64,7 @@ Feature: Generate API Blueprint documentation from test examples
       RspecApiDocumentation.configure do |config|
         config.app = App
         config.api_name = "Example API"
+        config.api_explanation = "Example API Description"
         config.format = :api_blueprint
         config.request_body_formatter = :json
         config.request_headers_to_include = %w[Content-Type Host]

features/html_documentation.feature

@@ -24,6 +24,7 @@ Feature: Generate HTML documentation from test examples
       RspecApiDocumentation.configure do |config|
         config.app = App
         config.api_name = "Example API"
+        config.api_explanation = "<p>Example API Description</p>"
         config.request_headers_to_include = %w[Cookie]
         config.response_headers_to_include = %w[Content-Type]
       end
@@ -66,6 +67,12 @@ Feature: Generate HTML documentation from test examples
       | Greetings |
     And   I should see the api name "Example API"
 
+  Scenario: Create an index with proper description
+      When  I open the index
+      Then  I should see the following resources:
+        | Greetings |
+      And   I should see the api explanation "Example API Description"
+
   Scenario: Example HTML documentation includes the parameters
     When  I open the index
     And   I navigate to "Greeting your favorite gem"

features/json_iodocs.feature

@@ -24,6 +24,7 @@ Feature: Json Iodocs
       RspecApiDocumentation.configure do |config|
         config.app = App
         config.api_name = "app"
+        config.api_explanation = "desc"
         config.format = :json_iodocs
         config.io_docs_protocol = "https"
       end
@@ -70,6 +71,7 @@ Feature: Json Iodocs
     {
       "app" : {
         "name" : "app",
+        "description": "desc",
         "protocol" : "https",
         "publicPath" : "",
         "baseURL" : null

features/markdown_documentation.feature

@@ -49,6 +49,7 @@ Feature: Generate Markdown documentation from test examples
       RspecApiDocumentation.configure do |config|
         config.app = App
         config.api_name = "Example API"
+        config.api_explanation = "Example API Description"
         config.format = :markdown
         config.request_headers_to_include = %w[Content-Type Host]
         config.response_headers_to_include = %w[Content-Type Content-Length]
@@ -148,6 +149,7 @@ Feature: Generate Markdown documentation from test examples
     Then the file "doc/api/index.markdown" should contain exactly:
     """
     # Example API
+    Example API Description
 
     ## Help
 

features/slate_documentation.feature

@@ -49,6 +49,7 @@ Feature: Generate Slate documentation from test examples
       RspecApiDocumentation.configure do |config|
         config.app = App
         config.api_name = "Example API"
+        config.api_explanation = "Description"
         config.format = :slate
         config.curl_host = 'http://localhost:3000'
         config.request_headers_to_include = %w[Content-Type Host]

features/textile_documentation.feature

@@ -49,6 +49,7 @@ Feature: Generate Textile documentation from test examples
       RspecApiDocumentation.configure do |config|
         config.app = App
         config.api_name = "Example API"
+        config.api_explanation = "Example API Description"
         config.format = :textile
         config.request_headers_to_include = %w[Content-Type Host]
         config.response_headers_to_include = %w[Content-Type Content-Length]
@@ -148,6 +149,7 @@ Feature: Generate Textile documentation from test examples
     Then the file "doc/api/index.textile" should contain exactly:
     """
     h1. Example API
+    Example API Description
 
     h2. Help
 

lib/rspec_api_documentation/configuration.rb

@@ -75,6 +75,7 @@ def self.add_setting(name, opts = {})
     add_setting :curl_host, :default => nil
     add_setting :keep_source_order, :default => false
     add_setting :api_name, :default => "API Documentation"
+    add_setting :api_explanation, :default => nil
     add_setting :io_docs_protocol, :default => "http"
     add_setting :request_headers_to_include, :default => nil
     add_setting :response_headers_to_include, :default => nil

lib/rspec_api_documentation/views/markup_index.rb

@@ -3,16 +3,14 @@
 module RspecApiDocumentation
   module Views
     class MarkupIndex < Mustache
+      delegate :api_name, :api_explanation, to: :@configuration, prefix: false
+
       def initialize(index, configuration)
         @index = index
         @configuration = configuration
         self.template_path = configuration.template_path
       end
 
-      def api_name
-        @configuration.api_name
-      end
-
       def sections
         RspecApiDocumentation::Writers::IndexHelper.sections(examples, @configuration)
       end

lib/rspec_api_documentation/writers/json_iodocs_writer.rb

@@ -94,6 +94,7 @@ def as_json(opts = nil)
         {
           @api_key.to_sym => {
             :name => @configuration.api_name,
+            :description => @configuration.api_explanation,
             :protocol => @configuration.io_docs_protocol,
             :publicPath => "",
             :baseURL => @configuration.curl_host

spec/configuration_spec.rb

@@ -52,6 +52,7 @@
     its(:curl_host) { should be_nil }
     its(:keep_source_order) { should be_falsey }
     its(:api_name) { should == "API Documentation" }
+    its(:api_explanation) { should be_nil }
     its(:client_method) { should == :client }
     its(:io_docs_protocol) { should == "http" }
     its(:request_headers_to_include) { should be_nil }

templates/rspec_api_documentation/html_index.mustache

@@ -10,7 +10,7 @@
 <body>
 <div class="container">
   <h1>{{ api_name }}</h1>
-
+  {{{ api_explanation }}}
   {{# sections }}
   <div class="article">
     <h2>{{ resource_name }}</h2>

templates/rspec_api_documentation/markdown_index.mustache

@@ -1,4 +1,5 @@
 # {{ api_name }}
+{{{ api_explanation }}}
 
 {{# sections }}
 ## {{ resource_name }}

templates/rspec_api_documentation/textile_index.mustache

@@ -1,4 +1,5 @@
 h1. {{ api_name }}
+{{{ api_explanation }}}
 
 {{# sections }}
 h2. {{ resource_name }}