allow overriding tag definitions

Author: mattyr

README.md

@@ -202,6 +202,7 @@ end
 * [token_owner](#token_owner)
 * [security_definitions](#security_definitions)
 * [models](#models)
+* [tags](#tags)
 * [hide_documentation_path](#hide_documentation_path)
 * [info](#info)
 
@@ -329,6 +330,18 @@ add_swagger_documentation \
    ]
 ```
 
+<a name="tags" />
+### tags:
+A list of tags to document.  By default tags are automatically generated
+for endpoints based on route names.
+
+```ruby
+add_swagger_documentation \
+  tags: [
+    { name: 'widgets', description: 'A description of widgets' }
+  ]
+```
+
 <a name="hide_documentation_path" />
 #### hide_documentation_path: (default: `true`)
 ```ruby

lib/grape-swagger/doc_methods.rb

@@ -53,6 +53,13 @@ def setup(options)
 
         paths, definitions   = endpoint.path_and_definition_objects(combi_routes, options)
         tags                 = GrapeSwagger::DocMethods::TagNameDescription.build(paths)
+
+        if options[:tags]
+          names = options[:tags].map{|t| t[:name]}
+          tags.reject!{|t| names.include?(t[:name])}
+          tags += options[:tags]
+        end
+
         output[:tags]        = tags unless tags.empty? || paths.blank?
         output[:paths]       = paths unless paths.blank?
         output[:definitions] = definitions unless definitions.blank?

spec/swagger_v2/default_api_spec.rb

@@ -132,4 +132,28 @@ def app
       expect(subject['contact']['email']).to eql('[email protected]')
     end
   end
+
+  context 'with tags' do
+    def app
+      Class.new(Grape::API) do
+        format :json
+        desc 'This gets something.'
+        get '/something' do
+          { bla: 'something' }
+        end
+        add_swagger_documentation tags: [
+          { name: 'something', description: 'customized description' }
+        ]
+      end
+    end
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    it 'documents the customized tag' do
+      expect(subject['tags']).to eql([{ 'name' => 'something', 'description' => 'customized description' }])
+    end
+  end
 end