Merge remote-tracking branch 'zipmark/master'

Author: justinko

.gitignore

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

Gemfile.lock

@@ -1,11 +1,10 @@
 PATH
   remote: .
   specs:
-    rspec_api_documentation (4.7.0)
+    rspec_api_documentation (4.9.0)
       activesupport (>= 3.0.0)
-      json (~> 1.4, >= 1.4.6)
       mustache (~> 1.0, >= 0.99.4)
-      rspec (~> 3.0, >= 3.0.0)
+      rspec (~> 3.0)
 
 GEM
   remote: http://rubygems.org/
@@ -76,7 +75,7 @@ GEM
     multi_json (1.11.2)
     multi_test (0.1.2)
     multipart-post (2.0.0)
-    mustache (1.0.2)
+    mustache (1.0.3)
     nokogiri (1.6.7.2)
       mini_portile2 (~> 2.0.0.rc2)
     pry (0.10.3)
@@ -158,4 +157,4 @@ DEPENDENCIES
   webmock (~> 1.7)
 
 BUNDLED WITH
-   1.11.2
+   1.13.6

README.md

@@ -14,6 +14,10 @@ Check out a [sample](http://rad-example.herokuapp.com).
 
 Please see the wiki for latest [changes](https://github.com/zipmark/rspec_api_documentation/wiki/Changes).
 
+## RSpec 3.5 Beta
+
+Use the `rspec-3.5` branch until RSpec 3.5 is out of beta.
+
 ## Installation
 
 Add rspec_api_documentation to your Gemfile
@@ -85,7 +89,7 @@ RspecApiDocumentation.configure do |config|
 
   # An array of output format(s).
   # Possible values are :json, :html, :combined_text, :combined_json,
-  #   :json_iodocs, :textile, :markdown, :append_json
+  #   :json_iodocs, :textile, :markdown, :append_json, :slate
   config.format = [:html]
 
   # Location of templates
@@ -369,6 +373,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.
@@ -396,8 +416,12 @@ Special values:
 
 * `:required => true` Will display a red '*' to show it's required
 * `:scope => :the_scope` Will scope parameters in the hash, scoping can be nested. See example
+* `:method => :method_name` Will use specified method as a parameter value
 
-The value of scoped parameters can be set with both scoped (`let(:order_item_item_id)`) and unscoped (`let(:item_id)`) methods. It always searches for the scoped method first and falls back to the unscoped method.
+Retrieving of parameter value goes through several steps:
+1. if `method` option is defined and test case responds to this method then this method is used;
+2. if test case responds to scoped method then this method is used;
+3. overwise unscoped method is used.
 
 ```ruby
 resource "Orders" do
@@ -408,10 +432,13 @@ resource "Orders" do
   post "/orders" do
     parameter :name, "Order Name", :required => true, :scope => :order
     parameter :item, "Order items", :scope => :order
-    parameter :item_id, "Item id", :scope => [:order, :item]
+    parameter :item_id, "Item id", :scope => [:order, :item], method: :custom_item_id
 
-    let(:name) { "My Order" } # OR let(:order_name) { "My Order" }
-    let(:item_id) { 1 } # OR let(:order_item_item_id) { 1 }
+    let(:name) { "My Order" }
+    # OR let(:order_name) { "My Order" }
+    let(:item_id) { 1 }
+    # OR let(:custom_item_id) { 1 }
+    # OR let(:order_item_item_id) { 1 }
 
     example "Creating an order" do
       params.should eq({

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

@@ -8,7 +8,10 @@ Feature: Generate HTML documentation from test examples
           request = Rack::Request.new(env)
           response = Rack::Response.new
           response["Content-Type"] = "application/json"
-          response.write({ "hello" => request.params["target"] }.to_json)
+          response.write({
+            "hello" => request.params["target"],
+            "more_greetings" => { "bonjour" => { "message" => "le monde" } }
+          }.to_json)
           response.finish
         end
       end
@@ -31,14 +34,15 @@ Feature: Generate HTML documentation from test examples
           parameter :scoped, "This is a scoped variable", :scope => :scope
           parameter :sub, "This is scoped", :scope => [:scope, :further]
 
-          response_field :hello, "The greeted thing"
+          response_field :hello,   "The greeted thing"
+          response_field :message, "Translated greeting", scope: [:more_greetings, :bonjour]
 
           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","more_greetings":{"bonjour":{"message":"le monde"}}}')
           end
         end
       end
@@ -71,12 +75,13 @@ Feature: Generate HTML documentation from test examples
       | scope[scoped]       | This is a scoped variable   |
       | scope[further][sub] | This is scoped              |
 
-  Scenario: Examle HTML documentation should include the response fields
+  Scenario: Example HTML documentation should include the response fields
     When  I open the index
     And   I navigate to "Greeting your favorite gem"
     Then  I should see the following response fields:
-      | name  | description       |
-      | hello | The greeted thing |
+      | name                             | description         |
+      | hello                            | The greeted thing   |
+      | more_greetings[bonjour][message] | Translated greeting |
 
   Scenario: Example HTML documentation includes the request information
     When  I open the index
@@ -99,5 +104,5 @@ Feature: Generate HTML documentation from test examples
       | Content-Length | 35               |
     And   I should see the following response body:
       """
-      { "hello": "rspec_api_documentation" }
+      { "hello": "rspec_api_documentation", "more_greetings": { "bonjour": { "message": "le monde" } } }
       """

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
@@ -226,14 +229,11 @@ Feature: Generate Markdown documentation from test examples
 
     ### Parameters
 
-    Name : name *- required -*
-    Description : Name of order
-
-    Name : amount *- required -*
-    Description : Amount paid
-
-    Name : description
-    Description : Some comments on the order
+    | Name | Description | Required | Scope |
+    |------|-------------|----------|-------|
+    | name | Name of order | true |  |
+    | amount | Amount paid | true |  |
+    | description | Some comments on the order | false |  |
 
     ### Request