Add configuration option: keep_source_order

 * Sorts examples by :description if true
 * Sorts resources by :resource_name if true

README.md

@@ -30,6 +30,7 @@ See the `example` folder for a sample Rails app that has been documented.
 - filter - Filter by example document type
 - exclusion_filter - Filter by example document type
 - url_prefix - Add before all links on the index page, useful if docs are located in `public/docs`
+- keep_source_order - By default examples and resources are ordered by description. Set to true keep the source order.
 
 ### Example Configuration
 `spec/spec_helper.rb`

lib/rspec_api_documentation/configuration.rb

@@ -56,6 +56,7 @@ def self.add_setting(name, opts = {})
     }
 
     add_setting :curl_host, :default => nil
+    add_setting :keep_source_order, :default => false
 
     def settings
       @settings ||= {}

lib/rspec_api_documentation/html_writer.rb

@@ -36,7 +36,7 @@ def initialize(index, configuration)
     end
 
     def sections
-      IndexWriter.sections(examples)
+      IndexWriter.sections(examples, @configuration)
     end
 
     def examples

lib/rspec_api_documentation/index_writer.rb

@@ -1,10 +1,11 @@
 module RspecApiDocumentation
   module IndexWriter
-    def sections(examples)
+    def sections(examples, configuration)
       resources = examples.group_by(&:resource_name).inject([]) do |arr, (resource_name, examples)|
-        arr << { :resource_name => resource_name, :examples => examples.sort_by(&:description) }
+        ordered_examples = configuration.keep_source_order ? examples : examples.sort_by(&:description)
+        arr << { :resource_name => resource_name, :examples => ordered_examples }
       end
-      resources.sort_by { |resource| resource[:resource_name] }
+      configuration.keep_source_order ? resources : resources.sort_by { |resource| resource[:resource_name] }
     end
     module_function :sections
   end

lib/rspec_api_documentation/json_writer.rb

@@ -34,7 +34,7 @@ def initialize(index, configuration)
     end
 
     def sections
-      IndexWriter.sections(examples)
+      IndexWriter.sections(examples, @configuration)
     end
 
     def examples

spec/configuration_spec.rb

@@ -50,6 +50,7 @@
     its(:app) { should be_nil }
     its(:curl_host) { should be_nil }
     its(:url_prefix) { should be_blank }
+    its(:keep_source_order) { should be_false }
   end
 
   describe "#define_groups" do

spec/index_writer_spec.rb

@@ -7,14 +7,33 @@
     let(:example_3) { stub(:resource_name => "Cart", :description => "Creating an cart") }
     let(:examples) { [example_1, example_2, example_3] }
 
-    subject { RspecApiDocumentation::IndexWriter.sections(examples) }
+    context "with default value for keep_source_order" do
+      let(:configuration) { RspecApiDocumentation::Configuration.new }
+      subject { RspecApiDocumentation::IndexWriter.sections(examples, configuration) }
 
-    it "should group examples by resource name" do
-      subject.map { |resource| resource[:resource_name] }.should == ["Cart", "Order"]
+      it "should group examples by resource name" do
+        subject.map { |resource| resource[:resource_name] }.should =~ ["Cart", "Order"]
+      end
+
+      it "should order resources by resource name" do
+        subject.map { |resource| resource[:resource_name] }.should == ["Cart", "Order"]
+      end
+
+      it "should order examples by description" do
+        subject.detect { |resource| resource[:resource_name] == "Order"}[:examples].should == [example_2, example_1]
+      end
     end
 
-    it "should order examples by description" do
-      subject.detect { |resource| resource[:resource_name] == "Order"}[:examples].should == [example_2, example_1]
+    context "with keep_source_order set to true" do
+      subject { RspecApiDocumentation::IndexWriter.sections(examples, stub(:keep_source_order => true)) }
+
+      it "should order resources by source code declaration" do
+        subject.map { |resource| resource[:resource_name] }.should == ["Order", "Cart"]
+      end
+
+      it "should order examples by source code declaration" do
+        subject.detect { |resource| resource[:resource_name] == "Order"}[:examples].should =~ [example_1, example_2]
+      end
     end
   end
 end