Allow specifying custom tags at the route level (#523)

The current logic to determine a route's set of tags is based solely on the route, which works in most cases, but isn't flexible when you want to override the tags.

The situation that led me here was the following setup:

```
prefix 'locations/:id'

resource :employees do
  desc 'Retrieve employees for a given location'

  get '/' do
    ...
  end
end
```

Which grouped the `/locations/:id/employees` under the `locations` namespace. This was undesirable, because almost all of the endpoints in our API are prefixed with `/locations/:id`, which meant that they were all grouped under the `locations` namespace.

Allowing an additional `tags` attribute on the `desc` method solved the issue for me.

```
desc 'Retrieve employees for a given location', tags: ['employees']
```

Author: Jordan Brown

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