Allow specifying custom tags at the route level

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 * [#520](https://github.com/ruby-grape/grape-swagger/pull/520): Response model can have required attributes - [@WojciechKo](https://github.com/WojciechKo).
 * [#510](https://github.com/ruby-grape/grape-swagger/pull/510): Use 'token_owner' instead of 'oauth_token' on Swagger UI endpoint authorization. - [@texpert](https://github.com/texpert).
+* [#523](https://github.com/ruby-grape/grape-swagger/pull/523): Allow specifying custom tags at the route level. - [@jordanfbrown](https://github.com/jordanfbrown).
 * Your contribution here.
 
 #### Fixes

README.md

@@ -391,6 +391,7 @@ add_swagger_documentation \
 * [Overriding Auto-Generated Nicknames](#overriding-auto-generated-nicknames)
 * [Specify endpoint details](#details)
 * [Overriding the route summary](#summary)
+* [Overriding the tags](#tags)
 * [Defining an endpoint as an array](#array)
 * [Using an options hash](#options)
 * [Overriding param type](#overriding-param-type)
@@ -481,6 +482,22 @@ end
 ```
 
 
+<a name="tags" />
+#### Overriding the tags
+
+Tags are used for logical grouping of operations by resources or any other qualifier. To override the
+tags array, add `tags: ['tag1', 'tag2']` after the description.
+
+```ruby
+namespace 'order' do
+  desc 'This will be your summary', tags: ['orders']
+  get :order_id do
+    ...
+  end
+end
+```
+
+
 <a name="array" />
 #### Defining an endpoint as an array
 

lib/grape-swagger/endpoint.rb

@@ -112,7 +112,7 @@ def method_object(route, options, path)
       method[:parameters]  = params_object(route)
       method[:security]    = security_object(route)
       method[:responses]   = response_object(route, options[:markdown])
-      method[:tags]        = tag_object(route)
+      method[:tags]        = route.options.fetch(:tags, tag_object(route))
       method[:operationId] = GrapeSwagger::DocMethods::OperationId.build(route, path)
       method.delete_if { |_, value| value.blank? }
 

spec/swagger_v2/endpoint_versioned_path_spec.rb

@@ -1,17 +1,21 @@
 require 'spec_helper'
 
 describe 'Grape::Endpoint#path_and_definitions' do
-  let(:api) do
-    item = Class.new(Grape::API) do
+  let(:item) do
+    Class.new(Grape::API) do
       version 'v1', using: :path
 
       resource :item do
         get '/'
       end
     end
+  end
+
+  let(:api) do
+    item_api = item
 
     Class.new(Grape::API) do
-      mount item
+      mount item_api
       add_swagger_documentation add_version: true
     end
   end
@@ -28,4 +32,21 @@
   it 'tags the endpoint with the resource name' do
     expect(subject.first['/v1/item'][:get][:tags]).to eq ['item']
   end
+
+  context 'when custom tags are specified' do
+    let(:item) do
+      Class.new(Grape::API) do
+        version 'v1', using: :path
+
+        resource :item do
+          desc 'Item description', tags: ['special-item']
+          get '/'
+        end
+      end
+    end
+
+    it 'tags the endpoint with the custom tags' do
+      expect(subject.first['/v1/item'][:get][:tags]).to eq ['special-item']
+    end
+  end
 end