RSpec doc title

README.rst

@@ -1401,6 +1401,19 @@ And then configure RSpec in this way:
 This way, when running in recording mode, only the tests that have been marked with the
 ``:show_in_doc`` metadata will be run, and hence only those will be used as examples.
 
+If you want to distinguish your recorded examples from one another, you can provide a ``doc_title``
+that will be displayed in the documentation later, like this:
+
+.. code:: ruby
+
+  it 'works', :show_in_doc, doc_title: 'A working example' do
+    expect_it.to work
+  end
+
+  it 'wont work', :show_in_doc, doc_title: 'A failing example' do
+    expect_it.not_to work
+  end
+
 Caveats
 -------
 

lib/apipie/extractor/recorder.rb

@@ -105,6 +105,7 @@ def record
         if @controller
           {:controller => @controller,
            :action => @action,
+           :doc_title => doc_title,
            :verb => @verb,
            :path => @path,
            :params => @params,
@@ -122,6 +123,10 @@ def record
       def api_description
       end
 
+      def doc_title
+        @doc_title ||= (RSpec.current_example.metadata[:doc_title] if 'RSpec'.safe_constantize)
+      end
+
       class Middleware
         def initialize(app)
           @app = app

lib/apipie/extractor/writer.rb

@@ -75,7 +75,7 @@ def desc_to_s(description)
       def ordered_call(call)
         call = call.stringify_keys
         ordered_call = OrderedHash.new
-        %w[title verb path versions query request_data response_data code show_in_doc recorded].each do |k|
+        %w[title verb path versions query doc_title request_data response_data code show_in_doc recorded].each do |k|
           next unless call.has_key?(k)
           ordered_call[k] = case call[k]
                      when ActiveSupport::HashWithIndifferentAccess