Merge pull request #124 from dblock/api-desc-and-params

Added ability to change the description and parameters of the API endpoints generated by grape-swagger.

Author: dblock

CHANGELOG.md

@@ -6,6 +6,7 @@
 * [#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).
 * [#114](https://github.com/tim-vandecasteele/grape-swagger/pull/114): Added support for generating nested models from composed Grape Entities - [@dspaeth-faber](https://github.com/dspaeth-faber).
+* [#124](https://github.com/tim-vandecasteele/grape-swagger/pull/124): Added ability to change the description and parameters of the API endpoints generated by grape-swagger - [@dblock](https://github.com/dblock).
 * Rewritten .gemspec and removed Jeweler - [@dblock](https://github.com/dblock).
 * Added `GrapeEntity::VERSION` - [@dblock](https://github.com/dblock).
 * Added Rubocop, Ruby-style linter - [@dblock](https://github.com/dblock).

README.md

@@ -129,6 +129,24 @@ A hash merged into the `info` key of the JSON documentation. This may contain:
 * `:license_url`: The URL of the license.
 * `:terms_of_service_url`: The URL of the API terms and conditions.
 
+#### api_documentation
+
+Customize the Swagger API documentation route, typically contains a `desc` field. The default description is "Swagger compatible API description".
+
+``` ruby
+add_swagger_documentation \
+   api_documentation: { desc: 'Reticulated splines API swagger-compatible documentation.' }
+```
+
+#### specific_api_documentation
+
+Customize the Swagger API specific documentation route, typically contains a `desc` field. The default description is "Swagger compatible API description for specific API".
+
+``` ruby
+add_swagger_documentation \
+   specific_api_documentation: { desc: 'Reticulated splines API swagger-compatible endpoint documentation.' }
+```
+
 ## Swagger Header Parameters
 
 Swagger also supports the documentation of parameters passed in the header. Since grape's ```params[]``` doesn't return header parameters we can specify header parameters seperately in a block after the description.

lib/grape-swagger.rb

@@ -54,7 +54,9 @@ def self.setup(options)
               models: [],
               info: {},
               authorizations: nil,
-              root_base_path: true
+              root_base_path: true,
+              api_documentation: { desc: 'Swagger compatible API description' },
+              specific_api_documentation: { desc: 'Swagger compatible API description for specific API' }
             }
 
             options = defaults.merge(options)
@@ -69,6 +71,8 @@ def self.setup(options)
             authorizations   = options[:authorizations]
             root_base_path   = options[:root_base_path]
             extra_info       = options[:info]
+            api_doc          = options[:api_documentation].dup
+            specific_api_doc = options[:specific_api_documentation].dup
             @@models         = options[:models] || []
 
             @@hide_documentation_path = options[:hide_documentation_path]
@@ -79,7 +83,8 @@ def self.setup(options)
               end
             end
 
-            desc 'Swagger compatible API description'
+            desc api_doc.delete(:desc), params: api_doc.delete(:params)
+            @last_description.merge!(api_doc)
             get @@mount_path do
               header['Access-Control-Allow-Origin']   = '*'
               header['Access-Control-Request-Method'] = '*'
@@ -118,13 +123,14 @@ def self.setup(options)
               output
             end
 
-            desc 'Swagger compatible API description for specific API', params: {
+            desc specific_api_doc.delete(:desc), params: {
               'name' => {
                 desc: 'Resource name of mounted API',
                 type: 'string',
                 required: true
               }
-            }
+            }.merge(specific_api_doc.delete(:params) || {})
+            @last_description.merge!(specific_api_doc)
             get "#{@@mount_path}/:name" do
               header['Access-Control-Allow-Origin']   = '*'
               header['Access-Control-Request-Method'] = '*'

spec/api_description_spec.rb

@@ -0,0 +1,41 @@
+require 'spec_helper'
+
+describe 'API Description' do
+  context 'with no additional options' do
+    subject do
+      Class.new(Grape::API) do
+        add_swagger_documentation
+      end
+    end
+
+    it 'describes the API with defaults' do
+      routes = subject.endpoints.first.routes
+      expect(routes.count).to eq 2
+      expect(routes.first.route_description).to eq 'Swagger compatible API description'
+      expect(routes.first.route_params).to eq({})
+      expect(routes.last.route_description).to eq 'Swagger compatible API description for specific API'
+      expect(routes.last.route_params).to eq('name' => { desc: 'Resource name of mounted API', type: 'string', required: true })
+    end
+  end
+
+  context 'with additional options' do
+    subject do
+      Class.new(Grape::API) do
+        add_swagger_documentation \
+          api_documentation: { desc: 'First', params: { x: 1 }, xx: 11 },
+          specific_api_documentation: { desc: 'Second', params: { y: 42 }, yy: 4242 }
+      end
+    end
+
+    it 'describes the API with defaults' do
+      routes = subject.endpoints.first.routes
+      expect(routes.count).to eq 2
+      expect(routes.first.route_description).to eq 'First'
+      expect(routes.first.route_params).to eq(x: 1)
+      expect(routes.first.route_xx).to eq(11)
+      expect(routes.last.route_description).to eq 'Second'
+      expect(routes.last.route_params).to eq('name' => { desc: 'Resource name of mounted API', type: 'string', required: true }, y: 42)
+      expect(routes.last.route_yy).to eq(4242)
+    end
+  end
+end