ruby-swagger 0.0.3 → 0.1.0

data/lib/ruby-swagger/grape/grape_template.rb

@@ -8,7 +8,6 @@ require 'ruby-swagger/data/security_definitions'
 
 module Swagger::Grape
   class Template
-
     def self.generate(base_class)
       swagger_doc = Swagger::Template.generate
 
@@ -31,12 +30,12 @@ module Swagger::Grape
         scheme.tokenUrl = 'https://'
         scopes = {}
         routes.scopes.uniq.each do |scope|
-          scopes[scope] = ""
+          scopes[scope] = ''
         end
         scheme.scopes = scopes
 
         swagger_doc.securityDefinitions = Swagger::Data::SecurityDefinitions.new
-        swagger_doc.securityDefinitions.add_param("oauth2", scheme)
+        swagger_doc.securityDefinitions.add_param('oauth2', scheme)
       end
 
       swagger_doc
@@ -62,6 +61,5 @@ module Swagger::Grape
 
       extract_all_types(new_types, all_types)
     end
-
   end
-end
+end

data/lib/ruby-swagger/grape/method.rb

@@ -3,7 +3,6 @@ require 'ruby-swagger/grape/type'
 
 module Swagger::Grape
   class Method
-
     attr_reader :operation, :types, :scopes
 
     def initialize(route_name, route)
@@ -22,40 +21,40 @@ module Swagger::Grape
 
     private
 
-    #generate the base of the operation
+    # generate the base of the operation
     def new_operation
       @operation = Swagger::Data::Operation.new
       @operation.tags = grape_tags
       @operation.operationId = @route.route_api_name if @route.route_api_name && @route.route_api_name.length > 0
       @operation.summary = @route.route_description
       @operation.description = (@route.route_detail && @route.route_detail.length > 0) ? @route.route_detail : @route.route_description
-      @operation.deprecated = @route.route_deprecated if @route.route_deprecated  #grape extension
+      @operation.deprecated = @route.route_deprecated if @route.route_deprecated # grape extension
 
       @operation
     end
 
-    #extract all the parameters from the method definition (in path, url, body)
+    # extract all the parameters from the method definition (in path, url, body)
     def operation_params
       extract_params_and_types
 
-      @params.each do |param_name, parameter|
+      @params.each do |_param_name, parameter|
         operation.add_parameter(parameter)
       end
     end
 
-    #extract the data about the response of the method
+    # extract the data about the response of the method
     def operation_responses
       @operation.responses = Swagger::Data::Responses.new
 
       # Include all the possible errors in the response (store the types, they are documented separately)
       (@route.route_errors || {}).each do |code, response|
-        error_response = {'description' => response['description'] || response[:description]}
+        error_response = { 'description' => response['description'] || response[:description] }
 
-        if entity = (response[:entity] || response['entity'])
+        if (entity = (response[:entity] || response['entity']))
           type = Object.const_get entity.to_s
 
           error_response['schema'] = {}
-          error_response['schema']['$ref'] = "#/definitions/#{type.to_s}"
+          error_response['schema']['$ref'] = "#/definitions/#{type}"
 
           remember_type(type)
         end
@@ -64,10 +63,10 @@ module Swagger::Grape
       end
 
       if @route.route_response.present? && @route.route_response[:entity].present?
-        rainbow_response = {'description' => 'Successful result of the operation'}
+        rainbow_response = { 'description' => 'Successful result of the operation' }
 
         type = Swagger::Grape::Type.new(@route.route_response[:entity].to_s)
-        current_obj = rainbow_response['schema'] = {}
+        rainbow_response['schema'] = {}
         remember_type(@route.route_response[:entity])
 
         # Include any response headers in the documentation of the response
@@ -77,9 +76,9 @@ module Swagger::Grape
             rainbow_response['headers'] ||= {}
 
             rainbow_response['headers'][header_key] = {
-                'description'=> header_value['description'] || header_value[:description],
-                'type'=> header_value['type'] || header_value[:type],
-                'format'=> header_value['format'] || header_value[:format]
+              'description' => header_value['description'] || header_value[:description],
+              'type' => header_value['type'] || header_value[:type],
+              'format' => header_value['format'] || header_value[:format]
             }
           end
         end
@@ -92,14 +91,14 @@ module Swagger::Grape
             rainbow_response['schema']['type'] = 'object'
             rainbow_response['schema']['properties'] = {
               @route.route_response[:root] => {
-                  'type' => 'array',
-                  'items' => type.to_swagger
+                'type' => 'array',
+                'items' => type.to_swagger
               }
             }
           else
             rainbow_response['schema']['type'] = 'object'
             rainbow_response['schema']['properties'] = {
-                @route.route_response[:root] => type.to_swagger
+              @route.route_response[:root] => type.to_swagger
             }
           end
 
@@ -117,11 +116,11 @@ module Swagger::Grape
         @operation.responses.add_response('200', Swagger::Data::Response.parse(rainbow_response))
       end
 
-      @operation.responses.add_response('default', Swagger::Data::Response.parse({'description' => 'Unexpected error'}))
+      @operation.responses.add_response('default', Swagger::Data::Response.parse({ 'description' => 'Unexpected error' }))
     end
 
     def operation_security
-      if @route.route_scopes #grape extensions
+      if @route.route_scopes # grape extensions
         security = Swagger::Data::SecurityRequirement.new
         security.add_requirement('oauth2', @route.route_scopes)
         @operation.security = [security]
@@ -132,7 +131,7 @@ module Swagger::Grape
       end
     end
 
-    #extract the tags
+    # extract the tags
     def grape_tags
       (@route.route_tags && !@route.route_tags.empty?) ? @route.route_tags : [@route_name.split('/')[1]]
     end
@@ -144,20 +143,20 @@ module Swagger::Grape
       path_params
 
       case @route.route_method.downcase
-        when 'get'
-          query_params
-        when 'delete'
-          query_params
-        when 'post'
-          body_params
-       when 'put'
-          body_params
-        when 'patch'
-          body_params
-        when 'head'
-          raise ArgumentError.new("Don't know how to handle the http verb HEAD for #{@route_name}")
-        else
-          raise ArgumentError.new("Don't know how to handle the http verb #{@route.route_method} for #{@route_name}")
+      when 'get'
+        query_params
+      when 'delete'
+        query_params
+      when 'post'
+        body_params
+      when 'put'
+        body_params
+      when 'patch'
+        body_params
+      when 'head'
+        raise ArgumentError.new("Don't know how to handle the http verb HEAD for #{@route_name}")
+      else
+        raise ArgumentError.new("Don't know how to handle the http verb #{@route.route_method} for #{@route_name}")
       end
 
       @params
@@ -166,14 +165,14 @@ module Swagger::Grape
     def header_params
       @params ||= {}
 
-      #include all the parameters that are in the headers
+      # include all the parameters that are in the headers
       if @route.route_headers
         @route.route_headers.each do |header_key, header_value|
-          @params[header_key] = {'name' => header_key,
-                                'in' => 'header',
-                                'required' => (header_value[:required] == true),
-                                'type' => 'string',
-                                'description' => header_value[:description]}
+          @params[header_key] = { 'name' => header_key,
+                                  'in' => 'header',
+                                  'required' => (header_value[:required] == true),
+                                  'type' => 'string',
+                                  'description' => header_value[:description] }
         end
       end
 
@@ -181,16 +180,15 @@ module Swagger::Grape
     end
 
     def path_params
-      #include all the parameters that are in the path
-
-      @route_name.scan(/\{[a-zA-Z0-9\-\_]+\}/).each do |parameter| #scan all parameters in the url
-        param_name = parameter[1..parameter.length-2]
-        @params[param_name] = {'name' => param_name,
-                               'in' => 'path',
-                               'required' => true,
-                               'type' => 'string'}
+      # include all the parameters that are in the path
+
+      @route_name.scan(/\{[a-zA-Z0-9\-\_]+\}/).each do |parameter| # scan all parameters in the url
+        param_name = parameter[1..parameter.length - 2]
+        @params[param_name] = { 'name' => param_name,
+                                'in' => 'path',
+                                'required' => true,
+                                'type' => 'string' }
       end
-
     end
 
     def query_params
@@ -207,15 +205,16 @@ module Swagger::Grape
     end
 
     def body_params
-      #include all the parameters that are in the content-body
+      # include all the parameters that are in the content-body
       return unless @route.route_params && @route.route_params.length > 0
 
-      root_param = Swagger::Data::Parameter.parse({'name' => 'body',
-                                                   'in' => 'body',
-                                                   'description' => 'the content of the request',
-                                                   'schema' => {'type' => 'object', 'properties' => {}}})
+      body_name = @operation.operationId ? "#{@operation.operationId}_body" : 'body'
+      root_param = Swagger::Data::Parameter.parse({ 'name' => body_name,
+                                                    'in' => 'body',
+                                                    'description' => 'the content of the request',
+                                                    'schema' => { 'type' => 'object', 'properties' => {} } })
 
-      #create the params schema
+      # create the params schema
       @route.route_params.each do |parameter|
         param_name = parameter.first
         param_value = parameter.last
@@ -224,25 +223,35 @@ module Swagger::Grape
         next if @params.keys.include?(param_name)
 
         if param_name.scan(/[0-9a-zA-Z_]+/).count == 1
-          #it's a simple parameter, adding it to the properties of the main object
+          # it's a simple parameter, adding it to the properties of the main object
           converted_param = Swagger::Grape::Param.new(param_value)
           schema.properties[param_name] = converted_param.to_swagger
           required_parameter(schema, param_name, param_value)
+          documented_paramter(schema, param_name, param_value)
           remember_type(converted_param.type_definition) if converted_param.has_type_definition?
         else
           schema_with_subobjects(schema, param_name, parameter.last)
         end
-
       end
 
-      schema= root_param.schema
+      schema = root_param.schema
       @params['body'] = root_param if !schema.properties.nil? && schema.properties.keys.length > 0
     end
 
+    # Can potentionelly be used for per-param documentation, for now used for example values
+    def documented_paramter(schema, name, parameter)
+      return if parameter.nil? || parameter[:documentation].nil?
+
+      unless parameter[:documentation][:example].nil?
+        schema['example'] ||= {}
+        schema['example'][name] = parameter[:documentation][:example]
+      end
+    end
+
     def required_parameter(schema, name, parameter)
       return if parameter.nil? || parameter[:required].nil? || parameter[:required] == false
 
-      schema['required'] ||= []
+      schema['required'] = [] unless schema['required'].is_a?(Array)
       schema['required'] << name
     end
 
@@ -255,6 +264,7 @@ module Swagger::Grape
       remember_type(converted_param.type_definition) if converted_param.has_type_definition?
 
       required_parameter(append_to, path.last, parameter)
+      documented_paramter(append_to, path.last, parameter)
     end
 
     def find_elem_in_schema(root, schema_path)
@@ -265,18 +275,17 @@ module Swagger::Grape
       return root if root['properties'][next_elem].nil?
 
       case root['properties'][next_elem]['type']
-        when 'array'
-          #to descend an array this must be an array of objects
-          root['properties'][next_elem]['items']['type'] = 'object'
-          root['properties'][next_elem]['items']['properties'] ||= {}
-
-          find_elem_in_schema(root['properties'][next_elem]['items'], schema_path)
-        when 'object'
-          find_elem_in_schema(root['properties'][next_elem], schema_path)
-        else
-          raise ArgumentError.new("Don't know how to handle the schema path #{schema_path.join('/')}")
+      when 'array'
+        # to descend an array this must be an array of objects
+        root['properties'][next_elem]['items']['type'] = 'object'
+        root['properties'][next_elem]['items']['properties'] ||= {}
+
+        find_elem_in_schema(root['properties'][next_elem]['items'], schema_path)
+      when 'object'
+        find_elem_in_schema(root['properties'][next_elem], schema_path)
+      else
+        raise ArgumentError.new("Don't know how to handle the schema path #{schema_path.join('/')}")
       end
-
     end
 
     # Store an object "type" seen on parameters or response types
@@ -290,6 +299,5 @@ module Swagger::Grape
 
       @types << type.to_s
     end
-
   end
 end

data/lib/ruby-swagger/grape/param.rb

@@ -2,7 +2,6 @@ require 'ruby-swagger/grape/type'
 
 module Swagger::Grape
   class Param
-
     def initialize(param)
       @param = param
     end
@@ -11,6 +10,8 @@ module Swagger::Grape
       swagger_param = {}
       swagger_param['description'] = @param[:desc]  if @param[:desc].present?
       swagger_param['default'] = @param[:default]   if @param[:default].present?
+      swagger_param['required'] = @param[:required] if @param.key?(:required)
+      swagger_param['enum'] = @param[:values] if @param[:values].present?
 
       swagger_param.merge! Swagger::Grape::Type.new(@param[:type]).to_swagger
 
@@ -28,6 +29,5 @@ module Swagger::Grape
     def type
       @param[:type].to_s || 'string'
     end
-
   end
-end
+end

data/lib/ruby-swagger/grape/route_path.rb

@@ -4,7 +4,6 @@ require 'ruby-swagger/grape/method'
 
 module Swagger::Grape
   class RoutePath
-
     attr_reader :types, :scopes
 
     def initialize(route_name)
@@ -32,6 +31,5 @@ module Swagger::Grape
 
       path
     end
-
   end
-end
+end

data/lib/ruby-swagger/grape/routes.rb

@@ -4,7 +4,6 @@ require 'ruby-swagger/grape/route_path'
 
 module Swagger::Grape
   class Routes
-
     attr_reader :types, :scopes
 
     def initialize(routes)
@@ -18,8 +17,7 @@ module Swagger::Grape
       paths = {}
 
       @routes.each do |route|
-
-        next if route.route_hidden == true  #implement custom "hidden" extension
+        next if route.route_hidden == true # implement custom "hidden" extension
 
         swagger_path_name = swagger_path_name(route)
         paths[swagger_path_name] ||= Swagger::Grape::RoutePath.new(swagger_path_name)
@@ -41,12 +39,11 @@ module Swagger::Grape
       grape_path_name = grape_route.route_path
       grape_prefix = grape_route.route_prefix
       grape_path_name.gsub!(/^\/#{grape_prefix}/, '') if grape_prefix
-      grape_path_name.gsub!(/^\/:version/, '') #remove api version - if any
-      grape_path_name.gsub!(/\(\.:format\)$/, '') #remove api format - if any
-      grape_path_name.gsub!(/\(\..+\)$/, '') #remove api format - if any
-      grape_path_name.gsub!(/\/:([a-zA-Z0-9_]+)/, '/{\1}')  #convert parameters from :format into {format}
+      grape_path_name.gsub!(/^\/:version/, '') # remove api version - if any
+      grape_path_name.gsub!(/\(\.:format\)$/, '') # remove api format - if any
+      grape_path_name.gsub!(/\(\..+\)$/, '') # remove api format - if any
+      grape_path_name.gsub!(/\/:([a-zA-Z0-9_]+)/, '/{\1}') # convert parameters from :format into {format}
       grape_path_name
     end
-
   end
-end
+end

data/lib/ruby-swagger/grape/type.rb

@@ -1,140 +1,67 @@
+require 'ruby-swagger/grape/entity'
+require 'ruby-swagger/grape/entity_exposure'
+require 'ruby-swagger/grape/entity_nesting_exposure'
+
 module Swagger::Grape
   class Type
-
-    attr_reader :discovered_types
+    attr_reader :discovered_types # needed?
 
     def initialize(type)
       @type = type.to_s || 'String'
+      @swagger_type = {}
     end
 
     def to_swagger(with_definition = true)
-      type_convert(@type.to_s, with_definition)
+      translate(@type, with_definition)
     end
 
     def sub_types
-      type = Object.const_get(@type)
-      return [] unless type.respond_to?(:exposures)
-
-      types = []
-
-      type.exposures.each do |property, definition|
-        types << definition[:using] if definition[:using].present?
-      end
-
-      types.uniq
+      Swagger::Grape::Entity.new(@type).sub_types
     end
 
     private
 
-    def type_convert(type, with_definition = true)
-      swagger_type = {}
-
+    def translate(type, with_definition)
       case type.downcase
-        when 'string'
-          swagger_type['type'] = 'string'
-        when 'integer'
-          swagger_type['type'] = 'integer'
-        when 'array'
-          swagger_type['type'] = 'array'
-          swagger_type['items'] = {'type' => 'string'}
-        when 'hash'
-          swagger_type['type'] = 'object'
-          swagger_type['properties'] = {}
-        when 'boolean'
-          swagger_type['type'] = 'boolean'
-        when 'virtus::attribute::boolean'
-          swagger_type['type'] = 'boolean'
-        when 'symbol'
-          swagger_type['type'] = 'string'
-        when 'float'
-          swagger_type['type'] = 'number'
-          swagger_type['format'] = 'float'
-        when 'rack::multipart::uploadedfile'
-          swagger_type['type'] = 'string'
-          STDERR.puts "Warning - I have no idea how to handle the type file. Right now I will consider this a string, but we should probably handle it..."
-        when 'date'
-          swagger_type['type'] = 'date'
-        when 'datetime'
-          swagger_type['type'] = 'string'
-          swagger_type['format'] = 'date-time'
+      when 'string'
+        @swagger_type['type'] = 'string'
+      when 'integer'
+        @swagger_type['type'] = 'integer'
+      when 'array'
+        @swagger_type['type'] = 'array'
+        @swagger_type['items'] = { 'type' => 'string' }
+      when 'hash'
+        @swagger_type['type'] = 'object'
+        @swagger_type['properties'] = {}
+      when 'boolean'
+        @swagger_type['type'] = 'boolean'
+      when 'virtus::attribute::boolean'
+        @swagger_type['type'] = 'boolean'
+      when 'symbol'
+        @swagger_type['type'] = 'string'
+      when 'float'
+        @swagger_type['type'] = 'number'
+        @swagger_type['format'] = 'float'
+      when 'rack::multipart::uploadedfile'
+        @swagger_type['type'] = 'string'
+        STDERR.puts 'Warning - I have no idea how to handle the type file. Right now I will consider this a string, but we should probably handle it...'
+      when 'date'
+        @swagger_type['type'] = 'string'
+        @swagger_type['format'] = 'date'
+      when 'datetime'
+        @swagger_type['type'] = 'string'
+        @swagger_type['format'] = 'date-time'
+      else
+
+        if with_definition
+          # I can just reference the name of the object here
+          @swagger_type['type'] = 'object'
+          @swagger_type['$ref'] = "#/definitions/#{type}"
         else
-          swagger_type['type'] = "object"
-
-          if with_definition
-            # I can just reference the name of the object here
-            swagger_type['$ref'] = "#/definitions/#{type}"
-          else
-            type = Object.const_get(@type)
-            # I need to define the full object
-            raise ArgumentError.new("Don't know how to translate the object #{@type}") unless type.respond_to?(:exposures)
-
-            swagger_type['properties'] = {}
-
-            type.exposures.each do |property, definition|
-
-              cursor = swagger_type
-              target = property.to_s
-
-              if definition[:nested]
-                # it's a nested parameter
-                path = target.split('__')
-                cursor = find_elem_in_schema(cursor, path.dup)
-                target = path.last
-              end
-
-              target = definition[:as].to_s if definition[:as].present?
-
-              cursor['properties'][target] = {}
-
-              if definition[:documentation].present? && definition[:documentation][:type].present?
-                cursor['properties'][target] = type_convert(definition[:documentation][:type].to_s, true)
-              end
-
-              if definition[:using].present?
-                #it's either an object or an array of object
-                using = type_convert(definition[:using].to_s, true)
-                
-                if definition['type'].present? && definition['type'] == 'array'
-                  cursor['properties'][target]['items'] = using
-                else
-                  cursor['properties'][target] = using
-                end
-              end
-
-              cursor['properties'][target]['description'] = definition[:documentation][:desc] if definition[:documentation].present?
-              cursor['properties'][target]['type'] ||= 'string'  #no type defined, assuming it's a string
-            end
-          end
-      end
-
-      swagger_type
-    end
-
-    def find_elem_in_schema(root, schema_path)
-      return root if schema_path.nil? || schema_path.empty?
-
-      next_elem = schema_path.shift
-
-      return root if root['properties'][next_elem].nil?
-
-      case root['properties'][next_elem]['type']
-        when 'array'
-          #to descend an array this must be an array of objects
-          root['properties'][next_elem]['items']['type'] = 'object'
-          root['properties'][next_elem]['items']['properties'] ||= {}
-
-          find_elem_in_schema(root['properties'][next_elem]['items'], schema_path)
-        when 'object'
-          find_elem_in_schema(root['properties'][next_elem], schema_path)
-        else
-          # I'm discending an object that before I assumed was something else
-          root['properties'][next_elem]['type'] = 'object'
-          root['properties'][next_elem]['properties'] ||= {}
-
-          find_elem_in_schema(root['properties'][next_elem], schema_path)
+          @swagger_type = Swagger::Grape::Entity.new(type).to_swagger
+        end
       end
-
+      @swagger_type
     end
-
   end
 end