APIB: allows routes with optional query strings

This allows for routes to be defined with optional querystrings, like:

```ruby
route '/orders/:id{?optional=:optional}', "Single Order" do
```

Before this, the http methods (e.g `get`, `post`) were injecting the
optional into the final URI. This moves optionals into another metadata
key (`options[:route_optionals]`).

Author: kurko

features/api_blueprint_documentation.feature

@@ -107,8 +107,9 @@ Feature: Generate API Blueprint documentation from test examples
           end
         end
 
-        route '/orders/{id}', "Single Order" do
+        route '/orders/:id{?optional=:optional}', "Single Order" do
           parameter :id, 'Order id', required: true, type: 'string', :example => '1'
+          parameter :optional
 
           attribute :name, 'The order name', required: true, :example => 'a name'
           attribute :amount, required: false
@@ -225,7 +226,7 @@ Feature: Generate API Blueprint documentation from test examples
           * Getting a list of orders
         POST Creates an order
           * Creating an order
-        /orders/{id} Single Order
+        /orders/:id{?optional=:optional} Single Order
         GET Returns a single order
           * Getting a specific order
         PUT Updates a single order
@@ -353,10 +354,11 @@ Feature: Generate API Blueprint documentation from test examples
               ]
             }
 
-    ## Single Order [/orders/{id}]
+    ## Single Order [/orders/:id{?optional=:optional}]
 
     + Parameters
       + id: 1 (required, string) - Order id
+      + optional
 
     + Attributes (object)
       + name: a name (required) - The order name

lib/rspec_api_documentation/dsl/resource.rb

@@ -47,7 +47,8 @@ def route(*args, &block)
         raise "You must define the route URI"  if args[0].blank?
         raise "You must define the route name" if args[1].blank?
         options = args.extract_options!
-        options[:route_uri] = args[0]
+        options[:route_uri] = args[0].gsub(/\{.*\}/, "")
+        options[:route_optionals] = (optionals = args[0].match(/(\{.*\})/) and optionals[-1])
         options[:route_name] = args[1]
         args.push(options)
         context(*args, &block)

lib/rspec_api_documentation/views/api_blueprint_index.rb

@@ -8,7 +8,7 @@ def initialize(index, configuration)
 
       def sections
         super.map do |section|
-          routes = section[:examples].group_by(&:route_uri).map do |route_uri, examples|
+          routes = section[:examples].group_by { |e| "#{e.route_uri}#{e.route_optionals}" }.map do |route, examples|
             attrs  = fields(:attributes, examples)
             params = fields(:parameters, examples)
 
@@ -23,7 +23,7 @@ def sections
             {
               "has_attributes?".to_sym => attrs.size > 0,
               "has_parameters?".to_sym => params.size > 0,
-              route_uri: route_uri,
+              route: route,
               route_name: examples[0][:route_name],
               attributes: attrs,
               parameters: params,

spec/dsl_spec.rb

@@ -594,13 +594,17 @@
     end
   end
 
-  route "/orders", "Orders Collection" do
+  route "/orders{?application_id=:some_id}", "Orders Collection" do
     attribute :description, "Order description"
 
     it "saves the route URI" do |example|
       expect(example.metadata[:route_uri]).to eq "/orders"
     end
 
+    it "saves the route optionals" do |example|
+      expect(example.metadata[:route_optionals]).to eq "{?application_id=:some_id}"
+    end
+
     it "saves the route name" do |example|
       expect(example.metadata[:route_name]).to eq "Orders Collection"
     end

spec/views/api_blueprint_index_spec.rb

@@ -7,10 +7,9 @@
   let(:post_group) { RSpec::Core::ExampleGroup.resource("Posts") }
   let(:comment_group) { RSpec::Core::ExampleGroup.resource("Comments") }
   let(:rspec_example_post_get) do
-    post_group.route "/posts/{id}", "Single Post" do
+    post_group.route "/posts/:id{?option=:option}", "Single Post" do
       parameter :id, "The id", required: true, type: "string", example: "1"
-      attribute :name, "Order name 1", required: true
-      attribute :name, "Order name 2", required: true
+      parameter :option
 
       get("/posts/{id}") do
         example_request 'Gets a post' do
@@ -25,15 +24,31 @@
   end
 
   let(:rspec_example_post_delete) do
-    post_group.route "/posts/{id}", "Single Post" do
-      get("/posts/{id}") do
+    post_group.route "/posts/:id", "Single Post" do
+      parameter :id, "The id", required: true, type: "string", example: "1"
+
+      delete("/posts/:id") do
         example_request 'Deletes a post' do
           do_request
         end
       end
     end
   end
 
+  let(:rspec_example_post_update) do
+    post_group.route "/posts/:id", "Single Post" do
+      parameter :id, "The id", required: true, type: "string", example: "1"
+      attribute :name, "Order name 1", required: true
+      attribute :name, "Order name 2", required: true
+
+      put("/posts/:id") do
+        example_request 'Updates a post' do
+          do_request
+        end
+      end
+    end
+  end
+
 
   let(:rspec_example_posts) do
     post_group.route "/posts", "Posts Collection" do
@@ -54,16 +69,13 @@
       end
     end
   end
-  let(:example1) { RspecApiDocumentation::Example.new(rspec_example_post_get, config) }
-  let(:example2) { RspecApiDocumentation::Example.new(rspec_example_post_delete, config) }
-  let(:example3) { RspecApiDocumentation::Example.new(rspec_example_posts, config) }
-  let(:example4) { RspecApiDocumentation::Example.new(rspec_example_comments, config) }
   let(:index) do
     RspecApiDocumentation::Index.new.tap do |index|
-      index.examples << example1
-      index.examples << example2
-      index.examples << example3
-      index.examples << example4
+      index.examples << RspecApiDocumentation::Example.new(rspec_example_post_get, config)
+      index.examples << RspecApiDocumentation::Example.new(rspec_example_post_delete, config)
+      index.examples << RspecApiDocumentation::Example.new(rspec_example_post_update, config)
+      index.examples << RspecApiDocumentation::Example.new(rspec_example_posts, config)
+      index.examples << RspecApiDocumentation::Example.new(rspec_example_comments, config)
     end
   end
   let(:config) { RspecApiDocumentation::Configuration.new }
@@ -82,12 +94,13 @@
 
       it "returns routes grouped" do
         comments_route = sections[0][:routes][0]
-        posts_route    = sections[1][:routes][0]
-        post_route     = sections[1][:routes][1]
+        posts_route = sections[1][:routes][0]
+        post_route = sections[1][:routes][1]
+        post_route_with_optionals = sections[1][:routes][2]
 
         comments_examples = comments_route[:http_methods].map { |http_method| http_method[:examples] }.flatten
         expect(comments_examples.size).to eq 1
-        expect(comments_route[:route_uri]).to eq "/comments"
+        expect(comments_route[:route]).to eq "/comments"
         expect(comments_route[:route_name]).to eq "Comments Collection"
         expect(comments_route[:has_parameters?]).to eq false
         expect(comments_route[:parameters]).to eq []
@@ -96,13 +109,13 @@
 
         post_examples = post_route[:http_methods].map { |http_method| http_method[:examples] }.flatten
         expect(post_examples.size).to eq 2
-        expect(post_route[:route_uri]).to eq "/posts/{id}"
+        expect(post_route[:route]).to eq "/posts/:id"
         expect(post_route[:route_name]).to eq "Single Post"
         expect(post_route[:has_parameters?]).to eq true
         expect(post_route[:parameters]).to eq [{
           required: true,
-          example: "1",
           type: "string",
+          example: "1",
           name: "id",
           description: "The id",
           properties_description: "required, string"
@@ -115,9 +128,29 @@
           properties_description: "required"
         }]
 
+        post_w_optionals_examples = post_route_with_optionals[:http_methods].map { |http_method| http_method[:examples] }.flatten
+        expect(post_w_optionals_examples.size).to eq 1
+        expect(post_route_with_optionals[:route]).to eq "/posts/:id{?option=:option}"
+        expect(post_route_with_optionals[:route_name]).to eq "Single Post"
+        expect(post_route_with_optionals[:has_parameters?]).to eq true
+        expect(post_route_with_optionals[:parameters]).to eq [{
+          required: true,
+          type: "string",
+          example: "1",
+          name: "id",
+          description: "The id",
+          properties_description: "required, string"
+        }, {
+          name: "option",
+          description: nil,
+          properties_description: nil
+        }]
+        expect(post_route_with_optionals[:has_attributes?]).to eq false
+        expect(post_route_with_optionals[:attributes]).to eq []
+
         posts_examples = posts_route[:http_methods].map { |http_method| http_method[:examples] }.flatten
         expect(posts_examples.size).to eq 1
-        expect(posts_route[:route_uri]).to eq "/posts"
+        expect(posts_route[:route]).to eq "/posts"
         expect(posts_route[:route_name]).to eq "Posts Collection"
         expect(posts_route[:has_parameters?]).to eq false
         expect(posts_route[:parameters]).to eq []

templates/rspec_api_documentation/api_blueprint_index.mustache

@@ -12,7 +12,7 @@ FORMAT: A1
 {{/ description }}
 {{# routes }}
 
-## {{ route_name }} [{{ route_uri }}]
+## {{ route_name }} [{{ route }}]
 {{# description }}
 
 description: {{ description }}