Adds swagger tags in swagger output

README.rst

@@ -222,6 +222,12 @@ param
 returns
   Look at `Response description`_ section for details.
 
+tags
+  Adds tags for grouping operations together in Swagger outputs. See `swagger`_
+  for more details. You can also provide tags in the `Resource Description`_
+  block so that they are automatically prepended to all action tags in the
+  controller.
+
 formats
   Method level request / response formats.
 

lib/apipie-rails.rb

@@ -15,6 +15,7 @@
 require "apipie/response_description"
 require "apipie/response_description_adapter"
 require "apipie/see_description"
+require "apipie/tag_list_description"
 require "apipie/validator"
 require "apipie/railtie"
 require 'apipie/extractor'

lib/apipie/dsl_definition.rb

@@ -32,10 +32,11 @@ def _apipie_dsl_data_init
          :api_args          => [],
          :api_from_routes   => nil,
          :errors            => [],
+         :tag_list          => [],
          :returns           => {},
          :params            => [],
          :headers           => [],
-         :resource_id        => nil,
+         :resource_id       => nil,
          :short_description => nil,
          :description       => nil,
          :examples          => [],
@@ -222,6 +223,13 @@ def error(code_or_options, desc=nil, options={}) #:doc:
         _apipie_dsl_data[:errors] << [code_or_options, desc, options]
       end
 
+      # Add tags to resources and actions group operations together.
+      def tags(*args)
+        return unless Apipie.active_dsl?
+        tags = args.length == 1 ? args.first : args
+        _apipie_dsl_data[:tag_list] += tags
+      end
+
       def _apipie_define_validators(description)
 
         # [re]define method only if validation is turned on

lib/apipie/method_description.rb

@@ -34,6 +34,8 @@ def initialize(method, resource, dsl_data)
         Apipie::ErrorDescription.from_dsl_data(args)
       end
 
+      @tag_list = dsl_data[:tag_list]
+
       @returns = dsl_data[:returns].map do |code,args|
         Apipie::ResponseDescription.from_dsl_data(self, code, args)
       end
@@ -94,6 +96,15 @@ def returns_self
       @returns
     end
 
+    def tag_list
+      all_tag_list = []
+      parent = Apipie.get_resource_description(@resource.controller.superclass)
+
+      # get tags from parent resource description
+      parent_tags = [parent, @resource].flat_map { |resource| resource._tag_list_arg }
+      Apipie::TagListDescription.new((parent_tags + @tag_list).uniq.compact)
+    end
+
     def returns
       all_returns = []
       parent = Apipie.get_resource_description(@resource.controller.superclass)

lib/apipie/resource_description.rb

@@ -14,8 +14,8 @@ module Apipie
   class ResourceDescription
 
     attr_reader :controller, :_short_description, :_full_description, :_methods, :_id,
-      :_path, :_name, :_params_args, :_returns_args, :_errors_args, :_formats, :_parent, :_metadata,
-      :_headers, :_deprecated
+      :_path, :_name, :_params_args, :_returns_args, :_tag_list_arg, :_errors_args,
+      :_formats, :_parent, :_metadata, :_headers, :_deprecated
 
     def initialize(controller, resource_name, dsl_data = nil, version = nil, &block)
 
@@ -42,6 +42,7 @@ def update_from_dsl_data(dsl_data)
       @_errors_args = dsl_data[:errors]
       @_params_args = dsl_data[:params]
       @_returns_args = dsl_data[:returns]
+      @_tag_list_arg = dsl_data[:tag_list]
       @_metadata = dsl_data[:meta]
       @_api_base_url = dsl_data[:api_base_url]
       @_headers = dsl_data[:headers]

lib/apipie/swagger_generator.rb

@@ -224,7 +224,7 @@ def add_ruby_method(paths, ruby_method)
         @current_http_method = method_key
 
         methods[method_key] = {
-            tags: [tag_name_for_resource(ruby_method.resource)] + warning_tags,
+            tags: [tag_name_for_resource(ruby_method.resource)] + warning_tags + ruby_method.tag_list.tags,
             consumes: params_in_body? ? ['application/json'] : ['application/x-www-form-urlencoded', 'multipart/form-data'],
             operationId: op_id,
             summary: Apipie.app.translate(api.short_description, @current_lang),

lib/apipie/tag_list_description.rb

@@ -0,0 +1,11 @@
+module Apipie
+
+  class TagListDescription
+
+    attr_reader :tags
+
+    def initialize(tags); @tags = tags; end
+
+  end
+
+end

spec/dummy/app/controllers/pets_controller.rb

@@ -395,6 +395,14 @@ def returns_response_with_invalid_array
   end
 
 
+  #-----------------------------------------------------------
+  # A method with simple tags.
+  #-----------------------------------------------------------
+  api!
+  tags(%w[Dogs Cats LivingBeings])
+  def show_plain_response_with_tags
+    render :plain => "showing pet properties"
+  end
 
 end
 

spec/dummy/app/controllers/tagged_cats_controller.rb

@@ -0,0 +1,32 @@
+#
+# The TagsController defined here provides an example of a resource_description
+# defining a set of tags for the contained methods to include.
+#
+
+class TaggedCatsController < ApplicationController
+  resource_description do
+    description 'A controller to test "returns"'
+    short 'Pets'
+    path '/pets'
+
+    tags(%w[Dogs Pets])
+  end
+
+  #-----------------------------------------------------------
+  # simple 'returns' example: a method that returns a cat record
+  #-----------------------------------------------------------
+  api :GET, "/pets/:id/as_properties", "Get a cat record"
+  tags(%w[Animals])
+  def show_as_properties
+    render :plain => "showing pet properties"
+  end
+
+  #-----------------------------------------------------------
+  # simple 'returns' example: a method that returns another cat record
+  #-----------------------------------------------------------
+  api :GET, "/pets/:id/as_same_properties", "Get a cat record"
+  tags("Puma", "Animals")
+  def show_as_same_properties
+    render :plain => "showing pet properties"
+  end
+end

spec/dummy/app/controllers/twitter_example_controller.rb

@@ -299,4 +299,9 @@ def index
     render :text => 'twitter example'
   end
 
+  api :GET, '/twitter_example/{id}/followers', 'Find the followers for the given screen name'
+  tags %w[following index search]
+  def followers
+    render :text => 'followers'
+  end
 end

spec/lib/swagger/rake_swagger_spec.rb

@@ -51,6 +51,10 @@ def expect_param_def(http_method, path, param_name, field, value)
       expect(param[field]).to eq(value)
     end
 
+    def expect_tags_def(http_method, path, value)
+      params = apidoc_swagger["paths"][path][http_method]["tags"]
+      expect(params).to eq(value)
+    end
 
     def body_param_def(http_method, path, param_name)
       params = apidoc_swagger["paths"][path][http_method]["parameters"]
@@ -88,6 +92,8 @@ def expect_body_param_def(http_method, path, param_name, field, value)
         expect_param_def("get", "/users/by_department", "department", "in", "query")
         expect_param_def("get", "/users/by_department", "department", "enum",
                          ["finance", "operations", "sales", "marketing", "HR"])
+
+        expect_tags_def("get", "/twitter_example/{id}/followers", %w[twitter_example following index search])
       end
 
       it "generates a valid swagger file" do
@@ -113,6 +119,8 @@ def expect_body_param_def(http_method, path, param_name, field, value)
         expect_param_def("get", "/users/by_department", "department", "enum",
                          ["finance", "operations", "sales", "marketing", "HR"])
 
+        expect_tags_def("get", "/twitter_example/{id}/followers", %w[twitter_example following index search])
+
       end
 
       it "generates a valid swagger file" do

spec/lib/swagger/response_validation_spec.rb

@@ -101,4 +101,4 @@
 
 
 
-end
+end

spec/lib/swagger/swagger_dsl_spec.rb

@@ -166,6 +166,19 @@ def have_field?(field, expected_name, breadcrumb)
 
     end
 
+    describe "PetsController#show_plain_response_with_tags" do
+      subject do
+        desc._methods[:show_plain_response_with_tags]
+      end
+
+      it "should return tags with 'Dogs', 'Cats', and 'LivingBeings'" do
+        returns_obj = subject.tag_list
+        puts returns_obj.inspect
+
+        expect(returns_obj.tags).to eq(%w[Dogs Cats LivingBeings])
+      end
+    end
+
     describe "PetsController#show_as_properties" do
       subject do
         desc._methods[:show_as_properties]
@@ -435,6 +448,40 @@ def have_field?(field, expected_name, breadcrumb)
 
   end
 
+  #==============================================================================
+  # TaggedCatsController is a demonstration of how tags may be defined in the
+  # controller's resource description so that they may be automatically prefixed
+  # to a particular operation's tags.
+  #==============================================================================
+
+  describe TaggedCatsController do
+    describe "TaggedCatsController#show_as_properties" do
+      subject do
+        desc._methods[:show_as_properties]
+      end
+
+      it "should return tags with 'Dogs', 'Pets', and 'Animals'" do
+        returns_obj = subject.tag_list
+        puts returns_obj.inspect
+
+        expect(returns_obj.tags).to eq(%w[Dogs Pets Animals])
+      end
+    end
+
+    describe "TaggedCatsController#show_as_same_properties" do
+      subject do
+        desc._methods[:show_as_same_properties]
+      end
+
+      it "should return tags with 'Dogs', 'Pets', 'Puma', and 'Animals'" do
+        returns_obj = subject.tag_list
+        puts returns_obj.inspect
+
+        expect(returns_obj.tags).to eq(%w[Dogs Pets Puma Animals])
+      end
+    end
+  end
+
   #==============================================================================
   # PetsUsingSelfDescribingClassesController is a demonstration of how
   # responses can be described using manual generation of a property description