Another attempt at adding explanations to resources

.gitignore

@@ -1,6 +1,7 @@
 tmp
 .rvmrc
 .ruby-version
+.ruby-gemset
 example/docs
 example/public/docs
 *.gem

README.md

@@ -369,6 +369,22 @@ resource "Orders" do
 end
 ```
 
+A resource can also have an explanation.
+
+```ruby
+resource "Orders" do
+  explanation "Orders are top-level business objects. They can be created by a POST request"
+  post "/orders" do
+    example "Creating an order" do
+      explanation "This method creates a new order."
+      do_request
+      # make assertions
+    end
+  end
+end
+```
+
+
 #### header
 
 This method takes the header name and value. The value can be a string or a symbol. If it is a symbol it will `send` the symbol, allowing you to `let` header values.

features/combined_json.feature

@@ -29,23 +29,25 @@ Feature: Combined text
       end
 
       resource "Greetings" do
+        explanation "Welcome to the party"
+
         get "/greetings" do
           parameter :target, "The thing you want to greet"
 
           example "Greeting your favorite gem" do
             do_request :target => "rspec_api_documentation"
 
-            response_headers["Content-Type"].should eq("text/plain")
-            status.should eq(200)
-            response_body.should eq('Hello, rspec_api_documentation!')
+            expect(response_headers["Content-Type"]).to eq("text/plain")
+            expect(status).to eq(200)
+            expect(response_body).to eq('Hello, rspec_api_documentation!')
           end
 
           example "Greeting your favorite developers of your favorite gem" do
             do_request :target => "Sam & Eric"
 
-            response_headers["Content-Type"].should eq("text/plain")
-            status.should eq(200)
-            response_body.should eq('Hello, Sam & Eric!')
+            expect(response_headers["Content-Type"]).to eq("text/plain")
+            expect(status).to eq(200)
+            expect(response_body).to eq('Hello, Sam & Eric!')
           end
         end
       end
@@ -70,6 +72,7 @@ Feature: Combined text
     [
       {
         "resource": "Greetings",
+        "resource_explanation": "Welcome to the party",
         "http_method": "GET",
         "route": "/greetings",
         "description": "Greeting your favorite gem",
@@ -106,6 +109,7 @@ Feature: Combined text
       },
       {
         "resource": "Greetings",
+        "resource_explanation": "Welcome to the party",
         "http_method": "GET",
         "route": "/greetings",
         "description": "Greeting your favorite developers of your favorite gem",

features/combined_text.feature

@@ -33,17 +33,17 @@ Feature: Combined text
           example "Greeting your favorite gem" do
             do_request :target => "rspec_api_documentation"
 
-            response_headers["Content-Type"].should eq("text/plain")
-            status.should eq(200)
-            response_body.should eq('Hello, rspec_api_documentation!')
+            expect(response_headers["Content-Type"]).to eq("text/plain")
+            expect(status).to eq(200)
+            expect(response_body).to eq('Hello, rspec_api_documentation!')
           end
 
           example "Greeting your favorite developers of your favorite gem" do
             do_request :target => "Sam & Eric"
 
-            response_headers["Content-Type"].should eq("text/plain")
-            status.should eq(200)
-            response_body.should eq('Hello, Sam & Eric!')
+            expect(response_headers["Content-Type"]).to eq("text/plain")
+            expect(status).to eq(200)
+            expect(response_body).to eq('Hello, Sam & Eric!')
           end
 
           example "Multiple Requests" do
@@ -145,6 +145,5 @@ Feature: Combined text
       Content-Type: text/plain
 
       Hello, Eric!
-
     """
 

features/curl.feature

@@ -26,7 +26,7 @@ Feature: cURL output
 
           example "Getting Foo" do
             do_request
-            response_body.should == "foo"
+            expect(response_body).to eq("foo")
           end
         end
       end

features/headers.feature

@@ -28,7 +28,7 @@ Feature: Specifying request headers
 
           example "Getting Foo" do
             do_request
-            response_body.should == "foo"
+            expect(response_body).to eq("foo")
           end
         end
       end

features/html_documentation.feature

@@ -36,9 +36,9 @@ Feature: Generate HTML documentation from test examples
           example "Greeting your favorite gem" do
             do_request :target => "rspec_api_documentation"
 
-            response_headers["Content-Type"].should eq("application/json")
-            status.should eq(200)
-            response_body.should eq('{"hello":"rspec_api_documentation"}')
+            expect(response_headers["Content-Type"]).to eq("application/json")
+            expect(status).to eq(200)
+            expect(response_body).to eq('{"hello":"rspec_api_documentation"}')
           end
         end
       end

features/json_iodocs.feature

@@ -35,17 +35,17 @@ Feature: Json Iodocs
           example "Greeting your favorite gem" do
             do_request :target => "rspec_api_documentation"
 
-            response_headers["Content-Type"].should eq("text/plain")
-            status.should eq(200)
-            response_body.should eq('Hello, rspec_api_documentation!')
+            expect(response_headers["Content-Type"]).to eq("text/plain")
+            expect(status).to eq(200)
+            expect(response_body).to eq('Hello, rspec_api_documentation!')
           end
 
           example "Greeting your favorite developers of your favorite gem" do
             do_request :target => "Sam & Eric"
 
-            response_headers["Content-Type"].should eq("text/plain")
-            status.should eq(200)
-            response_body.should eq('Hello, Sam & Eric!')
+            expect(response_headers["Content-Type"]).to eq("text/plain")
+            expect(status).to eq(200)
+            expect(response_body).to eq('Hello, Sam & Eric!')
           end
         end
       end

features/markdown_documentation.feature

@@ -59,17 +59,17 @@ Feature: Generate Markdown documentation from test examples
           response_field :page, "Current page"
 
           example_request 'Getting a list of orders' do
-            status.should eq(200)
-            response_body.should eq('{"page":1,"orders":[{"name":"Order 1","amount":9.99,"description":null},{"name":"Order 2","amount":100.0,"description":"A great order"}]}')
+            expect(status).to eq(200)
+            expect(response_body).to eq('{"page":1,"orders":[{"name":"Order 1","amount":9.99,"description":null},{"name":"Order 2","amount":100.0,"description":"A great order"}]}')
           end
         end
 
         get '/orders/:id' do
           let(:id) { 1 }
 
           example_request 'Getting a specific order' do
-            status.should eq(200)
-            response_body.should == '{"order":{"name":"Order 1","amount":100.0,"description":"A great order"}}'
+            expect(status).to eq(200)
+            expect(response_body).to eq('{"order":{"name":"Order 1","amount":100.0,"description":"A great order"}}')
           end
         end
 
@@ -82,7 +82,7 @@ Feature: Generate Markdown documentation from test examples
           let(:amount) { 33.0 }
 
           example_request 'Creating an order' do
-            status.should == 201
+            expect(status).to eq(201)
           end
         end
 
@@ -95,24 +95,26 @@ Feature: Generate Markdown documentation from test examples
           let(:name) { "Updated name" }
 
           example_request 'Updating an order' do
-            status.should == 200
+            expect(status).to eq(200)
           end
         end
 
         delete "/orders/:id" do
           let(:id) { 1 }
 
           example_request "Deleting an order" do
-            status.should == 200
+            expect(status).to eq(200)
           end
         end
       end
 
       resource 'Help' do
+        explanation 'Getting help'
+
         get '/help' do
           example_request 'Getting welcome message' do
-            status.should eq(200)
-            response_body.should == 'Welcome Henry !'
+            expect(status).to eq(200)
+            expect(response_body).to eq('Welcome Henry !')
           end
         end
 
@@ -149,6 +151,8 @@ Feature: Generate Markdown documentation from test examples
 
     ## Help
 
+    Getting help
+
     * [Getting welcome message](help/getting_welcome_message.markdown)
 
     ## Orders
@@ -212,7 +216,6 @@ Feature: Generate Markdown documentation from test examples
         }
       ]
     }</pre>
-
     """
 
   Scenario: Example 'Creating an order' file should look like we expect

features/oauth2_mac_client.feature

@@ -77,9 +77,9 @@ Feature: Use OAuth2 MAC client as a test client
           example "Greeting your favorite gem" do
             do_request :target => "rspec_api_documentation"
 
-            response_headers["Content-Type"].should eq("text/plain")
-            status.should eq(200)
-            response_body.should eq('hello rspec_api_documentation')
+            expect(response_headers["Content-Type"]).to eq("text/plain")
+            expect(status).to eq(200)
+            expect(response_body).to eq('hello rspec_api_documentation')
           end
         end
 
@@ -91,9 +91,9 @@ Feature: Use OAuth2 MAC client as a test client
           example "Greeting your favorite people" do
             do_request
 
-            response_headers["Content-Type"].should eq("text/plain")
-            status.should eq(200)
-            response_body.should eq("hello eric, sam")
+            expect(response_headers["Content-Type"]).to eq("text/plain")
+            expect(status).to eq(200)
+            expect(response_body).to eq("hello eric, sam")
           end
         end
 
@@ -105,9 +105,9 @@ Feature: Use OAuth2 MAC client as a test client
           example "Greeting your favorite companies" do
             do_request
 
-            response_headers["Content-Type"].should eq("text/plain")
-            status.should eq(200)
-            response_body.should eq("hello apple with mac and ios, google with search and mail")
+            expect(response_headers["Content-Type"]).to eq("text/plain")
+            expect(status).to eq(200)
+            expect(response_body).to eq("hello apple with mac and ios, google with search and mail")
           end
         end
 

features/patch.feature

@@ -24,7 +24,7 @@ Feature: Example Request with PATCH
       resource "Example Request" do
         patch "/" do
           example_request "Trying out patch" do
-            status.should eq(200)
+            expect(status).to eq(200)
           end
         end
       end

features/readme.md

@@ -30,7 +30,7 @@ See the wiki for additional setup. [Setting up RSpec API Documentation](https://
       get "/accounts" do
         example "Get a list of all accounts" do
           do_request
-          last_response.status.should be_ok
+          expect(last_response.status).to be_ok
         end
       end
 
@@ -42,7 +42,7 @@ See the wiki for additional setup. [Setting up RSpec API Documentation](https://
 
         example "Get an account", :document => :public do
           do_request
-          last_response.status.should be_ok
+          expect(last_response.status).to be_ok
         end
       end
     end

features/redefining_client.feature

@@ -23,7 +23,7 @@ Feature: Redefining the client method
 
         get "/" do
           example_request "Trying out get" do
-            status.should eq(200)
+            expect(status).to eq(200)
           end
         end
       end

features/textile_documentation.feature

@@ -59,17 +59,17 @@ Feature: Generate Textile documentation from test examples
           response_field :page, "Current page"
 
           example_request 'Getting a list of orders' do
-            status.should eq(200)
-            response_body.should eq('{"page":1,"orders":[{"name":"Order 1","amount":9.99,"description":null},{"name":"Order 2","amount":100.0,"description":"A great order"}]}')
+            expect(status).to eq(200)
+            expect(response_body).to eq('{"page":1,"orders":[{"name":"Order 1","amount":9.99,"description":null},{"name":"Order 2","amount":100.0,"description":"A great order"}]}')
           end
         end
 
         get '/orders/:id' do
           let(:id) { 1 }
 
           example_request 'Getting a specific order' do
-            status.should eq(200)
-            response_body.should == '{"order":{"name":"Order 1","amount":100.0,"description":"A great order"}}'
+            expect(status).to eq(200)
+            expect(response_body).to eq('{"order":{"name":"Order 1","amount":100.0,"description":"A great order"}}')
           end
         end
 
@@ -82,7 +82,7 @@ Feature: Generate Textile documentation from test examples
           let(:amount) { 33.0 }
 
           example_request 'Creating an order' do
-            status.should == 201
+            expect(status).to eq(201)
           end
         end
 
@@ -95,24 +95,26 @@ Feature: Generate Textile documentation from test examples
           let(:name) { "Updated name" }
 
           example_request 'Updating an order' do
-            status.should == 200
+            expect(status).to eq(200)
           end
         end
 
         delete "/orders/:id" do
           let(:id) { 1 }
 
           example_request "Deleting an order" do
-            status.should == 200
+            expect(status).to eq(200)
           end
         end
       end
 
       resource 'Help' do
+        explanation 'Getting help'
+
         get '/help' do
           example_request 'Getting welcome message' do
-            status.should eq(200)
-            response_body.should == 'Welcome Henry !'
+            expect(status).to eq(200)
+            expect(response_body).to eq('Welcome Henry !')
           end
         end
 
@@ -149,6 +151,8 @@ Feature: Generate Textile documentation from test examples
 
     h2. Help
 
+    Getting help
+
     * "Getting welcome message":help/getting_welcome_message.textile
 
     h2. Orders
@@ -160,7 +164,7 @@ Feature: Generate Textile documentation from test examples
     * "Updating an order":orders/updating_an_order.textile
     """
 
-  Scenario: Example 'Getting al ist of orders' file should look like we expect
+  Scenario: Example 'Getting a list of orders' file should look like we expect
     Then the file "doc/api/orders/getting_a_list_of_orders.textile" should contain exactly:
     """
     h1. Orders API