Added support for namespace descriptions.

Author: renier

CHANGELOG.md

@@ -1,5 +1,6 @@
 ### Next Release
 
+* [#94](https://github.com/tim-vandecasteele/grape-swagger/pull/94): Added support for namespace descriptions - [@renier](https://github.com/renier).
 * [#110](https://github.com/tim-vandecasteele/grape-swagger/pull/110), [#111](https://github.com/tim-vandecasteele/grape-swagger/pull/111) - Added `responseModel` support - [@bagilevi](https://github.com/bagilevi).
 * [#105](https://github.com/tim-vandecasteele/grape-swagger/pull/105): Fixed compatibility with Swagger-UI - [@CraigCottingham](https://github.com/CraigCottingham).
 * [#87](https://github.com/tim-vandecasteele/grape-swagger/pull/87): Fixed mapping of `default` to `defaultValue` - [@m-o-e](https://github.com/m-o-e).

lib/grape-swagger.rb

@@ -4,7 +4,7 @@
 module Grape
   class API
     class << self
-      attr_reader :combined_routes
+      attr_reader :combined_routes, :combined_namespaces
 
       def add_swagger_documentation(options = {})
         documentation_class = create_documentation_class
@@ -13,7 +13,6 @@ def add_swagger_documentation(options = {})
         mount(documentation_class)
 
         @combined_routes = {}
-
         routes.each do |route|
           route_match = route.route_path.split(route.route_prefix).last.match('\/([\w|-]*?)[\.\/\(]')
           next if route_match.nil?
@@ -24,6 +23,12 @@ def add_swagger_documentation(options = {})
           next if @@hide_documentation_path && route.route_path.include?(@@mount_path)
           @combined_routes[resource] << route
         end
+
+        @combined_namespaces = {}
+        endpoints.each do |endpoint|
+          ns = endpoint.settings.stack.last[:namespace]
+          @combined_namespaces[ns.space] = ns if ns
+        end
       end
 
       private
@@ -80,6 +85,7 @@ def self.setup(options)
               header['Access-Control-Request-Method'] = '*'
 
               routes = target_class.combined_routes
+              namespaces = target_class.combined_namespaces
 
               if @@hide_documentation_path
                 routes.reject! { |route, _value| "/#{route}/".index(parse_path(@@mount_path, nil) << '/') == 0 }
@@ -89,9 +95,13 @@ def self.setup(options)
                 next if routes[local_route].all?(&:route_hidden)
 
                 url_format  = '.{format}' unless @@hide_format
+
+                description = namespaces[local_route] && namespaces[local_route].options[:desc]
+                description ||= "Operations about #{local_route.pluralize}"
+
                 {
                   path: "/#{local_route}#{url_format}",
-                  description: "Operations about #{local_route.pluralize}"
+                  description: description
                 }
               end.compact
 

spec/grape-swagger_spec.rb

@@ -10,4 +10,7 @@
     Grape::API.should respond_to :add_swagger_documentation
   end
 
+  it 'added combined-namespaces' do
+    Grape::API.should respond_to :combined_namespaces
+  end
 end

spec/non_default_api_spec.rb

@@ -575,4 +575,31 @@ def app
     end
 
   end
+
+  context 'documented namespace description' do
+    before :all do
+      class NamespaceWithDescAPI < Grape::API
+        namespace :aspace, desc: 'Description for aspace' do
+          desc 'This gets something.'
+          get '/something' do
+            { bla: 'something' }
+          end
+        end
+        add_swagger_documentation format: :json
+      end
+      get '/swagger_doc'
+    end
+
+    def app
+      NamespaceWithDescAPI
+    end
+
+    subject do
+      JSON.parse(last_response.body)['apis'][0]
+    end
+
+    it 'shows the namespace description in the json spec' do
+      expect(subject['description']).to eql('Description for aspace')
+    end
+  end
 end