Merge pull request #354 from LeFnord/master

some improvements, see PR comment

Author: peter scholz

.gitignore

@@ -37,3 +37,4 @@ ToDo.md
 .ruby-version
 spec/params_entity_spec.rb
 vendor/bundle/
+spec/swagger_v2/x-dummy.rb

README.md

@@ -109,9 +109,11 @@ end
 <a name="configure" />
 ## Configure
 
-[target_class](#target_class)  
+[host](#host)  
+[mount_path](#mount_path)  
+[add_base_path](#add_base_path)  
+[add_version](#add_version)  
 [markdown](#markdown)  
-[hide_format](#hide_format)  
 [api_version](#api_version)  
 [models](#models)  
 [hide_documentation_path](#hide_documentation_path)  
@@ -123,16 +125,45 @@ You can pass a hash with optional configuration settings to ```add_swagger_docum
 *not all configuration options supported yet*, but is WIP
 
 
-#### target_class: <a name="target_class" />
-The API class to document, default `self`.
+`host` and `base_path` are also accepting a `proc` to evaluate.
 
+<a name="host" />
+#### host:
+Sets explicit the `host`
+```ruby
+add_swagger_documentation \
+   host: 'www.no-example.com'
+```
+
+<a name="base_path" />
+#### base_path:
+Base path of the API that's being exposed.
+```ruby
+add_swagger_documentation \
+   base_path: '/super/api'
+```
 
-#### *mount_path*:
+<a name="mount_path" />
+#### mount_path:
 The path where the API documentation is loaded, default is `/swagger_doc`.
+```ruby
+add_swagger_documentation \
+   mount_path: '/docu'
+```
 
+#### add_base_path:
+Add `basePath` key to the JSON documentation, default is `false`.
+```ruby
+add_swagger_documentation \
+   add_base_path: true
+```
 
-#### *class_name*:
-API class name.
+#### add_version:
+Add `version` key to the JSON documentation, default is `true`.
+```ruby
+add_swagger_documentation \
+   add_version: false
+```
 
 
 <a name="markdown" />
@@ -149,14 +180,6 @@ add_swagger_documentation \
   markdown: GrapeSwagger::Markdown::RedcarpetAdapter.new
 ```
 
-
-<a name="hide_format" />
-#### hide_format:
-
-~~Don't add `.(format)` to the end of URLs, default is `false`.~~
-`.(format)` would always be removed.
-
-
 <a name="api_version" />
 #### api_version:
 ```ruby
@@ -167,17 +190,10 @@ add_swagger_documentation \
 Version of the API that's being exposed.
 
 
-#### *base_path*:
-Base path of the API that's being exposed. This configuration parameter accepts a `proc` to evaluate `base_path`, useful when you need to use request attributes to determine its value.
-
-
 #### *authorizations*:
 This value is added to the `authorizations` key in the JSON documentation.
 
 
-#### *root_base_path*:
-Add `basePath` key to the JSON documentation, default is `true`.
-
 
 <a name="models" />
 #### models:
@@ -202,11 +218,6 @@ add_swagger_documentation \
 
 Don't show the `/swagger_doc` path in the generated swagger documentation.
 
-
-#### *format*:
-Documentation response format, default is `:json`.
-
-
 <a name="info" />
 #### info:
 ```ruby
@@ -226,7 +237,7 @@ add_swagger_documentation \
 A hash merged into the `info` key of the JSON documentation.
 
 
-#### *api_documentation*:
+<!-- #### *api_documentation*:
 Customize the Swagger API documentation route, typically contains a `desc` field. The default description is "Swagger compatible API description".
 
 ```ruby
@@ -241,7 +252,7 @@ Customize the Swagger API specific documentation route, typically contains a `de
 ```ruby
 add_swagger_documentation \
    specific_api_documentation: { desc: 'Reticulated splines API swagger-compatible endpoint documentation.' }
-```
+``` -->
 
 
 <a name="routes" />

lib/grape-swagger/doc_methods.rb

@@ -18,8 +18,6 @@ def setup(options)
       # options could be set on #add_swagger_documentation call,
       # for available options see #defaults
       target_class     = options[:target_class]
-      api_version      = options[:api_version]
-      extra_info       = options[:info]
       api_doc          = options[:api_documentation].dup
       specific_api_doc = options[:specific_api_documentation].dup
 
@@ -35,7 +33,6 @@ def setup(options)
         header['Access-Control-Request-Method'] = '*'
 
         output = swagger_object(
-          info_object(extra_info.merge(version: api_version)),
           target_class,
           request,
           options
@@ -63,7 +60,6 @@ def setup(options)
         error!({ error: 'named resource not exist' }, 400) if combined_routes.nil?
 
         output = swagger_object(
-          info_object(extra_info.merge(version: api_version)),
           target_class,
           request,
           options
@@ -80,19 +76,20 @@ def setup(options)
 
     def defaults
       {
+        info: {},
+        models: [],
+        scheme: %w( https http ),
         api_version: 'v1',
         target_class: nil,
         mount_path: '/swagger_doc',
         host: nil,
         base_path: nil,
+        add_base_path: false,
+        add_version: true,
         markdown: false,
         hide_documentation_path: true,
         format: :json,
-        models: [],
-        info: {},
-        scheme: %w( https http ),
         authorizations: nil,
-        root_base_path: true,
         api_documentation: { desc: 'Swagger compatible API description' },
         specific_api_documentation: { desc: 'Swagger compatible API description for specific API' }
       }

lib/grape-swagger/endpoint.rb

@@ -28,19 +28,29 @@ def content_types_for(target_class)
     # swagger spec2.0 related parts
     #
     # required keys for SwaggerObject
-    def swagger_object(info, target_class, request, options)
+    def swagger_object(target_class, request, options)
       {
-        info:           info,
+        info:           info_object(options[:info].merge(version: options[:api_version])),
         swagger:        '2.0',
         produces:       content_types_for(target_class),
         authorizations: options[:authorizations],
-        host:           request.env['HTTP_HOST'] || options[:host],
-        basePath:       request.env['SCRIPT_NAME'] || options[:base_path],
+        host:           optional_objects(:host, options, request.env['HTTP_HOST']),
+        basePath:       optional_objects(:base_path, options, request.env['SCRIPT_NAME']),
         tags:           tag_name_description(options),
         schemes:        options[:scheme]
       }.delete_if { |_, value| value.blank? }
     end
 
+    # helper for swagger object
+    # gets host and base_path
+    def optional_objects(key, options, request = nil)
+      if options[key]
+        options[key].is_a?(Proc) ? options[key].call : options[key]
+      else
+        request
+      end
+    end
+
     # building info object
     def info_object(infos)
       {
@@ -96,26 +106,13 @@ def path_item(routes, options)
       routes.each do |route|
         next if hidden?(route)
 
-        path = route.route_path
-        # always removing format
-        path.sub!(/\(\.\w+?\)$/, '')
-        path.sub!('(.:format)', '')
-        # ... format params
-        path.gsub!(/:(\w+)/, '{\1}')
-
-        # set item from path, this could be used for the definitions object
-        @item = path.gsub(%r{/{(.+?)}}, '').split('/').last.singularize.underscore.camelize || 'Item'
+        path = path_string(route, options)
         @entity = route.route_entity || route.route_success
 
         # ... replacing version params through submitted version
-        if options[:version]
-          path.sub!('{version}', options[:version])
-        else
-          path.sub!('{version}', '')
-        end
 
         method = route.route_method.downcase.to_sym
-        request_params = method_object(route, options)
+        request_params = method_object(route, options, path)
 
         if @paths.key?(path.to_sym)
           @paths[path.to_sym][method] = request_params
@@ -127,18 +124,54 @@ def path_item(routes, options)
       end
     end
 
-    def method_object(route, options)
+    def path_string(route, options)
+      path = route.route_path
+      # always removing format
+      path.sub!(/\(\.\w+?\)$/, '')
+      path.sub!('(.:format)', '')
+      # ... format params
+      path.gsub!(/:(\w+)/, '{\1}')
+
+      # set item from path, this could be used for the definitions object
+      @item = path.gsub(%r{/{(.+?)}}, '').split('/').last.singularize.underscore.camelize || 'Item'
+
+      if options[:version] && options[:add_version]
+        path.sub!('{version}', options[:version])
+      else
+        path.sub!('/{version}', '')
+      end
+
+      path = "/#{optional_objects(:base_path, options)}#{path}" if options[:add_base_path]
+
+      path
+    end
+
+    def method_object(route, options, path)
       method = {}
       method[:description] = description_object(route, options[:markdown])
       method[:headers]     = route.route_headers if route.route_headers
       method[:produces]    = produces_object(route, options)
       method[:parameters]  = params_object(route)
       method[:responses]   = response_object(route)
       method[:tags]        = tag_object(route, options[:version])
-
+      method[:operationId] = operation_id_object(route.route_method, path)
       method.delete_if { |_, value| value.blank? }
     end
 
+    def operation_id_object(method, path = nil)
+      verb = method.to_s.downcase
+      unless path.nil?
+        operation = path.split('/').map(&:capitalize).join
+        operation.gsub!(/\-(\w)/, &:upcase).delete!('-') if operation.include?('-')
+        operation.gsub!(/\_(\w)/, &:upcase).delete!('_') if operation.include?('_')
+        if path.include?('{')
+          operation.gsub!(/\{(\w)/, &:upcase)
+          operation.delete!('{').delete!('}')
+        end
+      end
+      "#{verb}#{operation}"
+    end
+
     def description_object(route, markdown)
       description = route.route_desc if route.route_desc.present?
       description = route.route_detail if route.route_detail.present?

spec/lib/endpoint_spec.rb

@@ -3,4 +3,19 @@
 describe Grape::Endpoint do
   subject { described_class.new(Grape::Util::InheritableSetting.new, {path: '/', method: :get}) }
 
+  describe 'operation_id_object' do
+    specify do
+      expect(subject.operation_id_object('GET')).to eql 'get'
+      expect(subject.operation_id_object('get')).to eql 'get'
+      expect(subject.operation_id_object(:get)).to eql 'get'
+      expect(subject.operation_id_object('GET', 'foo')).to eql 'getFoo'
+      expect(subject.operation_id_object('GET', '/foo')).to eql 'getFoo'
+      expect(subject.operation_id_object('GET', 'bar/foo')).to eql 'getBarFoo'
+      expect(subject.operation_id_object('GET', 'bar/foo{id}')).to eql 'getBarFooId'
+      expect(subject.operation_id_object('GET', '/bar_foo{id}')).to eql 'getBarFooId'
+      expect(subject.operation_id_object('GET', '/bar-foo{id}')).to eql 'getBarFooId'
+      expect(subject.operation_id_object('GET', '/simple_test/bar-foo{id}')).to eql 'getSimpleTestBarFooId'
+    end
+  end
+
 end

spec/support/api_swagger_v2_result.rb

@@ -72,6 +72,7 @@ class ApiError < Grape::Entity
       "swagger"=>"2.0",
       "produces"=>["application/json"],
       "host"=>"example.org",
+      "basePath"=>"/api",
       "tags"=>[{"name"=>"other_thing", "description"=>"Operations about other_things"},
         {"name"=>"thing", "description"=>"Operations about things"},
         {"name"=>"thing2", "description"=>"Operations about thing2s"},
@@ -84,6 +85,7 @@ class ApiError < Grape::Entity
             "parameters"=>[
               {"in"=>"array", "name"=>"elements", "description"=>"Set of configuration", "type"=>"string", "required"=>true, "allowMultiple"=>true, "items"=>{"type"=>"string"}}],
               "tags"=>["other_thing"],
+              "operationId"=>"getV3OtherThingElements",
               "responses"=>{"200"=>{"description"=>"nested route inside namespace", "schema"=>{"$ref"=>"#/definitions/QueryInput"}}},
               "x-amazon-apigateway-auth"=>{"type"=>"none"},
               "x-amazon-apigateway-integration"=>{"type"=>"aws", "uri"=>"foo_bar_uri", "httpMethod"=>"get"}}},
@@ -95,7 +97,8 @@ class ApiError < Grape::Entity
               {"in"=>"query", "name"=>"text", "description"=>"Content of something.", "type"=>"string", "required"=>false, "allowMultiple"=>false},
               {"in"=>"query", "name"=>"links", "description"=>nil, "type"=>"link", "required"=>false, "allowMultiple"=>true},
               {"in"=>"query", "name"=>"others", "description"=>nil, "type"=>"text", "required"=>false, "allowMultiple"=>false}],
-              "tags"=>["thing"],
+            "tags"=>["thing"],
+            "operationId"=>"getThing",
             "responses"=>{
               "200"=>{"description"=>"This gets Things.", "schema"=>{"$ref"=>"#/definitions/Thing"}},
               "401"=>{"description"=>"Unauthorized", "schema"=>{"$ref"=>"#/definitions/ApiError"}}}},
@@ -105,6 +108,7 @@ class ApiError < Grape::Entity
               {"in"=>"formData", "name"=>"text", "description"=>"Content of something.", "type"=>"string", "required"=>true, "allowMultiple"=>false},
               {"in"=>"body", "name"=>"links", "description"=>nil, "type"=>"Array", "required"=>true, "allowMultiple"=>true}],
             "tags"=>["thing"],
+            "operationId"=>"postThing",
             "responses"=>{
               "201"=>{"description"=>"This creates Thing.", "schema"=>{"$ref"=>"#/definitions/Something"}},
               "422"=>{"description"=>"Unprocessible Entity"}}
@@ -115,6 +119,7 @@ class ApiError < Grape::Entity
             "parameters"=>[
               {"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "required"=>true, "allowMultiple"=>false, "format"=>"int32"}],
             "tags"=>["thing"],
+            "operationId"=>"getThingId",
             "responses"=>{
               "200"=>{"description"=>"getting a single thing", "schema"=>{"$ref"=>"#/definitions/Thing"}},
               "401"=>{"description"=>"Unauthorized"}}},
@@ -125,17 +130,20 @@ class ApiError < Grape::Entity
               {"in"=>"formData", "name"=>"text", "description"=>"Content of something.", "type"=>"string", "required"=>false, "allowMultiple"=>false},
               {"in"=>"body", "name"=>"links", "description"=>nil, "type"=>"Array", "required"=>false, "allowMultiple"=>true}],
             "tags"=>["thing"],
+            "operationId"=>"putThingId",
             "responses"=>{"200"=>{"description"=>"This updates Thing.", "schema"=>{"$ref"=>"#/definitions/Something"}}}},
           "delete"=>{
             "produces"=>["application/json"],
             "parameters"=>[{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "required"=>true, "allowMultiple"=>false, "format"=>"int32"}],
             "tags"=>["thing"],
+            "operationId"=>"deleteThingId",
             "responses"=>{"200"=>{"description"=>"This deletes Thing.", "schema"=>{"$ref"=>"#/definitions/Something"}}}
         }},
         "/thing2"=>{
           "get"=>{
             "produces"=>["application/json"],
             "tags"=>["thing2"],
+            "operationId"=>"getThing2",
             "responses"=>{
               "200"=>{"description"=>"get Horses", "schema"=>{"$ref"=>"#/definitions/Something"}},
               "401"=>{"description"=>"HorsesOutError", "schema"=>{"$ref"=>"#/definitions/ApiError"}}}
@@ -145,6 +153,7 @@ class ApiError < Grape::Entity
             "produces"=>["application/json"],
             "parameters"=>[{"in"=>"path", "name"=>"id", "description"=>nil, "type"=>"integer", "required"=>true, "allowMultiple"=>false, "format"=>"int32"}],
             "tags"=>["dummy"],
+            "operationId"=>"deleteDummyId",
             "responses"=>{"200"=>{"description"=>"dummy route."}, "401"=>{"description"=>"Unauthorized"}}
       }}},
       "definitions"=>{