ruby-swagger 0.0.1

data/lib/ruby-swagger/data/url.rb

@@ -0,0 +1,26 @@
+require 'addressable/uri'
+
+module Swagger::Data
+  class Url
+
+    SCHEMES = %w(http https)
+
+    attr_reader :url
+
+    def initialize(url)
+      @url = url
+    end
+
+    def valid?
+      parsed = Addressable::URI.parse(url) or return false
+      SCHEMES.include?(parsed.scheme)
+    rescue Addressable::URI::InvalidURIError
+      false
+    end
+
+    def to_swagger
+      url
+    end
+
+  end
+end

data/lib/ruby-swagger/data/xml_object.rb

@@ -0,0 +1,15 @@
+require 'ruby-swagger/object'
+
+module Swagger::Data
+  class XMLObject < Swagger::Object #https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#xmlObject
+
+    attr_swagger :name, :namespace, :prefix, :attribute, :wrapped
+
+    def self.parse(xml_object)
+      return nil unless xml_object
+
+      Swagger::Data::XMLObject.new.bulk_set(xml_object)
+    end
+
+  end
+end

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

@@ -0,0 +1,2 @@
+require 'ruby-swagger/grape/grape_presenter'
+require 'ruby-swagger/grape/grape_config'

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

@@ -0,0 +1,160 @@
+require 'active_support/concern'
+
+module Grape
+  module DSL
+    module Configuration
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+
+        def api_desc(description, options = {}, &block)
+          default_api_options!(options)
+          block.call if block_given?
+          desc description, @api_options
+        end
+
+        def headers(headers_value)
+          raise ArgumentError.new("Grape::headers - unrecognized value #{headers_value} - allowed: Hash") unless headers_value.is_a?(Hash)
+
+          @api_options[:headers] = headers_value
+        end
+
+        def api_name(name_value)
+          raise ArgumentError.new("Grape::api_name - unrecognized value #{name_value} - allowed: String") unless name_value.is_a?(String)
+
+          @api_options[:api_name] = name_value
+        end
+
+        def deprecated(deprecation_value)
+          raise ArgumentError.new("Grape::deprecated - unrecognized value #{deprecation_value} - allowed: true|false") unless deprecation_value == true || deprecation_value == false
+
+          @api_options[:deprecated] = deprecation_value
+        end
+
+        def hidden(hidden_value)
+          raise ArgumentError.new("Grape::hidden - unrecognized value #{hidden_value} - allowed: true|false") unless hidden_value == true || hidden_value == false
+
+          @api_options[:hidden] = hidden_value
+        end
+
+        def detail(detail_value)
+          raise ArgumentError.new("Grape::detail - unrecognized value #{detail_value} - allowed: String") unless detail_value.is_a?(String)
+
+          @api_options[:detail] = detail_value
+        end
+
+        def scopes(scopes_value)
+          return if scopes_value.nil?
+
+          if scopes_value.is_a?(Array)
+            scopes_value.each do |scope|
+              raise ArgumentError.new("Grape::scopes - unrecognized scope #{scope_value}") unless scope.is_a?(String)
+            end
+
+            @api_options[:scopes] = scopes_value
+          elsif scopes_value.is_a?(String)
+            @api_options[:scopes] = [scopes_value]
+          else
+            raise ArgumentError.new("Grape::scopes - unrecognized value #{scopes_value} - scopes can either be a string or an array of strings")
+          end
+        end
+
+        def tags(new_tags)
+          raise ArgumentError.new("Grape::tags - unrecognized value #{new_tags} - tags can only be an array of strings or a string") unless new_tags.is_a?(Array) || new_tags.is_a?(String)
+
+          if new_tags.is_a?(String)
+            new_tags = [new_tags]
+          end
+
+          @api_options[:tags]= new_tags
+        end
+
+        def response(new_result, options = {})
+          raise ArgumentError.new("Grape::response - response can't be nil") unless new_result
+
+          response_obj = {entity: new_result}
+          response_obj[:root] = options[:root] || options['root']
+          response_obj[:headers] = options[:headers] || options['headers']
+          response_obj[:isArray] = options[:isArray] || options['isArray']
+
+          @api_options[:response]= response_obj
+        end
+
+        def errors(errors_value)
+          raise ArgumentError.new("Grape::errors - unrecognized value #{errors_value} - errors root must be a hash of errors") unless errors_value.is_a?(Hash)
+          @api_options[:errors]= errors_value
+        end
+
+        @@headers = {}
+        def default_headers(new_value)
+          @@headers = new_value
+        end
+
+        @@deprecated = false
+        def default_deprecated(new_value)
+          @@deprecated = new_value
+        end
+
+        @@hidden = false
+        def default_hidden(new_value)
+          @@hidden = new_value
+        end
+
+        @@scopes = nil
+        def default_scopes(new_value)
+          @@scopes = new_value
+        end
+
+        @@tags = []
+        def default_tags(new_value)
+          @@tags = new_value
+        end
+
+        @@result = nil
+        def default_result(new_value)
+          @@result = new_value
+        end
+
+        @@errors = nil
+        def default_errors(new_value)
+          @@errors = new_value
+        end
+
+        @@response_headers = nil
+        def default_response_headers(new_value)
+          @@response_headers = new_value
+        end
+
+        @@response_root = nil
+        def default_response_root(new_value)
+          @@response_root = new_value
+        end
+
+        @@response_entity = nil
+        def default_response_entity(new_value)
+          @@response_entity = new_value
+        end
+
+        def default_api_options!(options)
+          @api_options = {
+              headers: @@headers,
+              deprecated: @@deprecated,
+              hidden: @@hidden,
+              scopes: @@scopes,
+              tags: @@tags,
+              response: {
+                  entity: @@response_entity,
+                  root: @@response_root,
+                  headers: @@response_headers,
+                  isArray: false
+              },
+              errors: @@errors,
+              api_name: nil,
+              detail: ''
+          }.merge(options)
+          @description = ''
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+require 'active_support/concern'
+
+module Grape
+  module DSL
+    module InsideRoute
+      def api_present(*args)
+
+        args_list = args || []
+        options = {}
+
+        # Initialize the options hash - either by assigning to the current options for the method or with a new one
+        if args_list.count == 2
+
+          if args_list.last.kind_of?(Hash)
+            options = args_list.last
+          else
+            raise ArgumentError.new "The expected second argument for api_present is a Hash, but I got a #{args_list.last.class}"
+          end
+
+        elsif args_list.count == 1
+
+          #Initialize the option list
+          args_list << options
+
+        elsif args_list.count > 2 || args_list.count == 0
+          raise ArgumentError.new "Invalid number of arguments - got #{args_list.count}. expected 1 or 2 parameters"
+        end
+
+        # Setting the grape :with
+        if route.route_response.present? && route.route_response[:entity].present? &&!options[:with].present? && route.route_response[:entity].kind_of?(Class)
+          options[:with] = route.route_response[:entity]
+        end
+
+        # Setting the grape :root
+        if route.route_response.present? && route.route_response[:root].present? && !options[:root].present? && route.route_response[:root].kind_of?(String)
+          options[:root] = route.route_response[:root]
+        end
+
+        # Setting the :current_user extension
+        if defined?(current_user)
+          options[:current_user] = current_user
+        end
+
+        present *args_list
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+require 'ruby-swagger/data/document'
+require 'ruby-swagger/template'
+require 'ruby-swagger/data/definitions'
+require 'ruby-swagger/grape/routes'
+require 'ruby-swagger/grape/type'
+require 'ruby-swagger/data/security_scheme'
+require 'ruby-swagger/data/security_definitions'
+
+module Swagger::Grape
+  class Template
+
+    def self.generate(base_class)
+      swagger_doc = Swagger::Template.generate
+
+      routes = Swagger::Grape::Routes.new(base_class.routes)
+
+      swagger_doc.paths = routes.to_swagger
+      swagger_doc.definitions = Swagger::Data::Definitions.new
+
+      extract_all_types(routes.types).sort.each do |type|
+        grape_type = Swagger::Grape::Type.new(type)
+
+        swagger_doc.definitions.add_definition(type.to_s, grape_type.to_swagger(false))
+      end
+
+      if routes.scopes.present?
+        scheme = Swagger::Data::SecurityScheme.new
+        scheme.type = 'oauth2'
+        scheme.flow = 'accessCode'
+        scheme.authorizationUrl = 'https://'
+        scheme.tokenUrl = 'https://'
+        scopes = {}
+        routes.scopes.uniq.each do |scope|
+          scopes[scope] = ""
+        end
+        scheme.scopes = scopes
+
+        swagger_doc.securityDefinitions = Swagger::Data::SecurityDefinitions.new
+        swagger_doc.securityDefinitions.add_param("oauth2", scheme)
+      end
+
+      swagger_doc
+    end
+
+    def self.extract_all_types(types, all_types = [])
+      return all_types.uniq if types.length == 0
+
+      new_types = []
+
+      types.each do |type|
+        all_types << type.to_s unless all_types.include?(type.to_s)
+
+        grape_type = Swagger::Grape::Type.new(type)
+
+        grape_type.sub_types.each do |new_type|
+          unless all_types.include?(new_type.to_s)
+            new_types << new_type.to_s
+            all_types << new_type.to_s
+          end
+        end
+      end
+
+      extract_all_types(new_types, all_types)
+    end
+
+  end
+end

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

@@ -0,0 +1,295 @@
+require 'ruby-swagger/data/operation'
+require 'ruby-swagger/grape/type'
+
+module Swagger::Grape
+  class Method
+
+    attr_reader :operation, :types, :scopes
+
+    def initialize(route_name, route)
+      @route_name = route_name
+      @route = route
+      @types = []
+      @scopes = []
+
+      new_operation
+      operation_params
+      operation_responses
+      operation_security
+
+      self
+    end
+
+    private
+
+    #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
+    end
+
+    #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|
+        operation.add_parameter(parameter)
+      end
+    end
+
+    #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]}
+
+        if entity = (response[:entity] || response['entity'])
+          type = Object.const_get entity.to_s
+
+          error_response['schema'] = {}
+          error_response['schema']['$ref'] = "#/definitions/#{type.to_s}"
+
+          remember_type(type)
+        end
+
+        @operation.responses.add_response(code, Swagger::Data::Response.parse(error_response))
+      end
+
+      if @route.route_response.present? && @route.route_response[:entity].present?
+        rainbow_response = {'description' => 'Successful result of the operation'}
+
+        type = Swagger::Grape::Type.new(@route.route_response[:entity].to_s)
+        current_obj = rainbow_response['schema'] = {}
+        remember_type(@route.route_response[:entity])
+
+        # Include any response headers in the documentation of the response
+        if @route.route_response[:headers].present?
+          @route.route_response[:headers].each do |header_key, header_value|
+            next unless header_value.present?
+            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]
+            }
+          end
+        end
+
+        if @route.route_response[:root].present?
+          # A case where the response contains a single key in the response
+
+          if @route.route_response[:isArray] == true
+            # an array that starts from a key named root
+            rainbow_response['schema']['type'] = 'object'
+            rainbow_response['schema']['properties'] = {
+              @route.route_response[:root] => {
+                  'type' => 'array',
+                  'items' => type.to_swagger
+              }
+            }
+          else
+            rainbow_response['schema']['type'] = 'object'
+            rainbow_response['schema']['properties'] = {
+                @route.route_response[:root] => type.to_swagger
+            }
+          end
+
+        else
+
+          if @route.route_response[:isArray] == true
+            rainbow_response['schema']['type'] = 'array'
+            rainbow_response['schema']['items'] = type.to_swagger
+          else
+            rainbow_response['schema'] = type.to_swagger
+          end
+
+        end
+
+        @operation.responses.add_response('200', Swagger::Data::Response.parse(rainbow_response))
+      end
+
+      @operation.responses.add_response('default', Swagger::Data::Response.parse({'description' => 'Unexpected error'}))
+    end
+
+    def operation_security
+      if @route.route_scopes #grape extensions
+        security = Swagger::Data::SecurityRequirement.new
+        security.add_requirement('oauth2', @route.route_scopes)
+        @operation.security = [security]
+
+        @route.route_scopes.each do |scope|
+          @scopes << scope unless @scopes.include?(scope)
+        end
+      end
+    end
+
+    #extract the tags
+    def grape_tags
+      (@route.route_tags && !@route.route_tags.empty?) ? @route.route_tags : [@route_name.split('/')[1]]
+    end
+
+    def extract_params_and_types
+      @params = {}
+
+      header_params
+      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}")
+      end
+
+      @params
+    end
+
+    def header_params
+      @params ||= {}
+
+      #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]}
+        end
+      end
+
+      @params
+    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'}
+      end
+
+    end
+
+    def query_params
+      @route.route_params.each do |parameter|
+        next if @params[parameter.first.to_s]
+
+        swag_param = Swagger::Data::Parameter.from_grape(parameter)
+        next unless swag_param
+
+        swag_param.in = 'query'
+
+        @params[parameter.first.to_s] = swag_param
+      end
+    end
+
+    def body_params
+      #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' => {}}})
+
+      #create the params schema
+      @route.route_params.each do |parameter|
+        param_name = parameter.first
+        param_value = parameter.last
+        schema = root_param.schema
+
+        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
+          converted_param = Swagger::Grape::Param.new(param_value)
+          schema.properties[param_name] = converted_param.to_swagger
+          required_parameter(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
+      @params['body'] = root_param if !schema.properties.nil? && schema.properties.keys.length > 0
+    end
+
+    def required_parameter(schema, name, parameter)
+      return if parameter.nil? || parameter[:required].nil? || parameter[:required] == false
+
+      schema['required'] ||= []
+      schema['required'] << name
+    end
+
+    def schema_with_subobjects(schema, param_name, parameter)
+      path = param_name.scan(/[0-9a-zA-Z_]+/)
+      append_to = find_elem_in_schema(schema, path.dup)
+      converted_param = Swagger::Grape::Param.new(parameter)
+      append_to['properties'][path.last] = converted_param.to_swagger
+
+      remember_type(converted_param.type_definition) if converted_param.has_type_definition?
+
+      required_parameter(append_to, path.last, parameter)
+    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
+          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
+    def remember_type(type)
+      @types ||= []
+
+      return if %w(string integer boolean float array symbol virtus::attribute::boolean rack::multipart::uploadedfile date datetime).include?(type.to_s.downcase)
+
+      type = Object.const_get type.to_s
+      return if @types.include?(type.to_s)
+
+      @types << type.to_s
+    end
+
+  end
+end