allow overriding tag definitions (#589)

* allow overriding tag definitions

* add changelog, address rubocop issues

* add second tag to customized tag spec to make spec clearer

* bump travis

Author: mattyr

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 * [#583](https://github.com/ruby-grape/grape-swagger/pull/583): Issue #582: document file response - [@LeFnord](https://github.com/LeFnord).
 * [#588](https://github.com/ruby-grape/grape-swagger/pull/588): Allow extension keys in Info object - [@mattyr](https://github.com/mattyr).
+* [#589](https://github.com/ruby-grape/grape-swagger/pull/589): Allow overriding tag definitions in Info object - [@mattyr](https://github.com/mattyr).
 
 * Your contribution here.
 

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

@@ -52,7 +52,8 @@ def setup(options)
         )
 
         paths, definitions   = endpoint.path_and_definition_objects(combi_routes, options)
-        tags                 = GrapeSwagger::DocMethods::TagNameDescription.build(paths)
+        tags                 = tags_from(paths, options)
+
         output[:tags]        = tags unless tags.empty? || paths.blank?
         output[:paths]       = paths unless paths.blank?
         output[:definitions] = definitions unless definitions.blank?
@@ -109,5 +110,17 @@ def class_variables_from(options)
       @@class_name              = options[:class_name] || options[:mount_path].delete('/')
       @@hide_documentation_path = options[:hide_documentation_path]
     end
+
+    def tags_from(paths, 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
+
+      tags
+    end
   end
 end

spec/swagger_v2/default_api_spec.rb

@@ -139,4 +139,37 @@ def app
       expect(subject['x-logo']).to eql('http://logo.com/img.png')
     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
+        get '/somethingelse' do
+          { bla: 'somethingelse' }
+        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' => 'somethingelse', 'description' => 'Operations about somethingelses' },
+          { 'name' => 'something', 'description' => 'customized description' }
+        ]
+      )
+    end
+  end
 end