Add optional title attribute to the code examples

README.rst

@@ -1117,11 +1117,15 @@ The data is written into ``doc/apipie_examples.yml``. By default,
 only the first example is shown for each action. You can customize
 this by setting ``show_in_doc`` attribute at each example.
 
+You can add a title to the examples (useful when showing more than
+one example per method) by adding a 'title' attribute.
+
 .. code::
 
    --- !omap
      - announcements#index:
        - !omap
+         - title: This is a custom title for this example
          - verb: :GET
          - path: /api/blabla/1
          - versions:

lib/apipie/configuration.rb

@@ -6,7 +6,8 @@ class Configuration
       :default_version, :debug, :version_in_url, :namespaced_resources,
       :validate, :validate_value, :validate_presence, :validate_key, :authenticate, :doc_path,
       :show_all_examples, :process_params, :update_checksum, :checksum_path,
-      :link_extension, :record, :languages, :translate, :locale, :default_locale
+      :link_extension, :record, :languages, :translate, :locale, :default_locale,
+      :persist_show_in_doc
 
     alias_method :validate?, :validate
     alias_method :required_by_default?, :required_by_default
@@ -91,6 +92,10 @@ def ignored
       @ignored.map(&:to_s)
     end
 
+    # Persist the show_in_doc value in the examples if true. Use this if you
+    # cannot set the flag in the tests themselves (no rspec for example).
+    attr_writer :persist_show_in_doc
+
     # comment to put before docs that was generated automatically. It's used to
     # determine if the description should be overwritten next recording.
     # If you want to keep the documentation (prevent from overriding), remove
@@ -152,6 +157,7 @@ def initialize
       @default_locale = 'en'
       @locale = lambda { |locale| @default_locale }
       @translate = lambda { |str, locale| str }
+      @persist_show_in_doc = false
     end
   end
 end

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[verb path versions query request_data response_data code show_in_doc recorded].each do |k|
+        %w[title verb path versions query 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
@@ -97,15 +97,37 @@ def merge_old_new_examples
         merged_examples = []
         (new_examples.keys + old_examples.keys).uniq.each do |key|
           if new_examples.has_key?(key)
-            records = new_examples[key]
+            if old_examples.has_key?(key)
+              records = deep_merge_examples(new_examples[key], old_examples[key])
+            else
+              records = new_examples[key]
+            end
           else
             records = old_examples[key]
           end
-          merged_examples << [key, records.map { |r|  ordered_call(r) } ]
+          merged_examples << [key, records.map { |r| ordered_call(r) } ]
         end
         return merged_examples
       end
 
+      def deep_merge_examples(new_examples, old_examples)
+        new_examples.map do |new_example|
+          # Use ordered to get compareble output (mainly for the :query)
+          new_example_ordered = ordered_call(new_example.dup)
+
+          # Comparing verb, versions and query
+          if old_example = old_examples.find{ |old_example| old_example["verb"] == new_example_ordered["verb"] && old_example["versions"] == new_example_ordered["versions"] && old_example["query"] == new_example_ordered["query"]}
+
+            # Take the 'show in doc' attribute from the old example if it is present and the configuration requests the value to be persisted.
+            new_example[:show_in_doc] = old_example["show_in_doc"] if Apipie.configuration.persist_show_in_doc && old_example["show_in_doc"].to_i > 0
+
+            # Always take the title from the old example if it exists.
+            new_example[:title] ||= old_example["title"] if old_example["title"].present?
+          end
+          new_example
+        end 
+      end
+
       def load_new_examples
         @collector.records.reduce({}) do |h, (method, calls)|
           showed_in_versions = Set.new

lib/apipie/method_description.rb

@@ -174,7 +174,9 @@ def format_example_data(data)
     end
 
     def format_example(ex)
-      example = "#{ex[:verb]} #{ex[:path]}"
+      example = ""
+      example << "// #{ex[:title]}\n" if ex[:title].present?
+      example << "#{ex[:verb]} #{ex[:path]}"
       example << "?#{ex[:query]}" unless ex[:query].blank?
       example << "\n" << format_example_data(ex[:request_data]).to_s if ex[:request_data]
       example << "\n" << ex[:code].to_s