restspec 0.0.4 → 0.1

data/lib/restspec/endpoints/url_builder.rb

@@ -0,0 +1,51 @@
+module Restspec
+  module Endpoints
+    class URLBuilder
+      attr_reader :url_params
+
+      PARAM_INTERPOLATION_REGEX = /:([\w]+)/
+
+      def initialize(path = '', url_params = {}, query_params = {})
+        self.path = path
+        self.url_params = unbox_url_params(url_params)
+        self.query_params = query_params
+      end
+
+      def full_url
+        base_url + path_from_params + query_string
+      end
+
+      private
+
+      attr_accessor :path, :query_params
+      attr_writer :url_params
+
+      def path_from_params
+        path.gsub(PARAM_INTERPOLATION_REGEX) do
+          url_params[$1] || url_params[$1.to_sym]
+        end
+      end
+
+      def base_url
+        @base_url ||= (Restspec.config.base_url || '')
+      end
+
+      def query_string
+        @query_string ||= fill_query_string(query_params.to_param)
+      end
+
+      def fill_query_string(query_string)
+        query_string.present? ? "?#{query_string}" : ""
+      end
+
+      def unbox_url_params(raw_url_params)
+        params = raw_url_params.inject({}) do |hash, (key, value)|
+          real_value = value.respond_to?(:call) ? value.call : value
+          hash.merge(key.to_sym => real_value)
+        end
+
+        Restspec::Values::SuperHash.new(params)
+      end
+    end
+  end
+end

data/lib/restspec/rspec/api_macros.rb

@@ -56,7 +56,7 @@ module Restspec
 
             -> do
               endpoint.execute_once(
-                body: payload.merge(@payload || {}),
+                body: payload,
                 url_params: url_params.merge(resource_params).merge(@url_params || {}),
                 query_params: query_params.merge(@query_params || {}),
                 before: ->do
@@ -72,7 +72,7 @@ module Restspec
           subject { response }
 
           let(:payload) do
-            defined?(example_payload) ? example_payload : {}
+            defined?(example_payload) ? example_payload : nil
           end
 
           let(:url_params) do

data/lib/restspec/rspec/matchers/be_like_schema.rb

@@ -3,7 +3,7 @@ RSpec::Matchers.define :be_like_schema do |schema_name = nil|
     schema = if schema_name.present?
       Restspec::SchemaStore.get(schema_name)
     else
-      response.endpoint.schema
+      response.endpoint.schema_for(:response)
     end
 
     body = response.respond_to?(:body) ? response.body : response

data/lib/restspec/rspec/matchers/be_like_schema_array.rb

@@ -3,7 +3,7 @@ RSpec::Matchers.define :be_like_schema_array do |schema_name = nil|
     schema = if schema_name.present?
       Restspec::SchemaStore.get(schema_name)
     else
-      response.endpoint.schema
+      response.endpoint.schema_for(:response)
     end
 
     body = response.respond_to?(:body) ? response.body : response

data/lib/restspec/runners/docs/templates/docs.md.erb

@@ -1,8 +1,8 @@
 # API
 ## Hello World
 
-<% namespace_store.each do |namespace| %>
-## <%= namespace.name.capitalize %>
+<% namespace_store.each do |name, namespace| %>
+## <%= name.capitalize %>
 
 <% namespace.all_endpoints.each do |endpoint| %>
 ### <%= endpoint.name.capitalize %> [<%= endpoint.method.upcase %> <%= endpoint.full_path %>]

data/lib/restspec/schema/attribute.rb

@@ -1,8 +1,45 @@
 module Restspec
   module Schema
+    # An attribute is a part of a schema. All attributes have a name and a type at least.
+    # A type is an instance of a subclass of {Restspec::Schema::Types::BasicType} that keeps
+    # information about what are valid instances of the attribute and can generate valid
+    # instances of the attribute.
+    #
+    # @example
+    #
+    #   string_type = Types::StringType.new
+    #   name_attr = Attribute.new(:name, type)
+    #
+    #   string_type.example_for(name_attr) # A random word
+    #   string_type.valid?(name_attr, 1000) # false
+    #   string_type.valid?(name_attr, 'John') # true
+    #
+    # @example With the :example option
+    #
+    #   string_type = Types::StringType.new
+    #   name_attr = Attribute.new(:name, type, example: 'Example!')
+    #
+    #   string_type.example_for(name_attr) # Example!
+    #
     class Attribute
       attr_reader :name, :type
 
+      # Creates an attribute. It uses an identifier (name), an instance
+      # of a subclass of {Restspec::Schema::Types::BasicType} and a set
+      # of options.
+      #
+      # @param name the name of the attribute
+      # @param type an instance of a subclass of {Restspec::Schema::Types::BasicType} that
+      #   works like the type of this attribute, allowing the type to generate examples and
+      #   run validations based on this attribute.
+      # @param options that can be the following:
+      #   - **example**: A callable object (eg: a lambda) that returns something.
+      #   - **for**: Defines what abilities this attributes has.
+      #     This is an array that can contains none, some or all the symbols
+      #     `:checks` and `:examples`. This option defaults to `[:checks, :examples]`,
+      #     allowing the attribute to be used for run validations from {Checker#check!}
+      #     and for generating examples from {SchemaExample#value}.
+      # @return A new instance of Attribtue.
       def initialize(name, type, options = {})
         self.name = name
         self.type = type
@@ -10,14 +47,20 @@ module Restspec
         self.allowed_abilities = options.fetch(:for, [:checks, :examples])
       end
 
+      # The inner example in the attribute created calling the :example option
+      # when generating examples.
+      #
+      # @return The inner example created using the :example option.
       def example
         @example ||= example_override
       end
 
+      # @return [true, false] if the attribute has the ability to generate examples or not
       def can_generate_examples?
         allowed_abilities.include?(:examples)
       end
 
+      # @return [true, false] if the attribute has the ability to be checked
       def can_be_checked?
         allowed_abilities.include?(:checks)
       end

data/lib/restspec/schema/attribute_example.rb

@@ -2,7 +2,17 @@ require 'faker'
 
 module Restspec
   module Schema
-    class AttributeExample < Struct.new(:attribute)
+    # Generates an example for a single attribute.
+    class AttributeExample
+      # Creates a new {AttributeExample} with an {Attribute} object.
+      def initialize(attribute)
+        self.attribute = attribute
+      end
+
+      # Generates an example using the hardcoded `example_override` option
+      # in the attribute or by calling the #example_for method of the type.
+      #
+      # @return [#as_json] the generated example attribute.
       def value
         if attribute.example.present?
           attribute.example.try(:call) || attribute.example
@@ -13,6 +23,8 @@ module Restspec
 
       private
 
+      attr_accessor :attribute
+
       def type
         attribute.type
       end

data/lib/restspec/schema/checker.rb

@@ -1,33 +1,105 @@
 module Restspec
   module Schema
-    class Checker < Struct.new(:schema)
+    # Checks if a response object (a hash, esentially) is valid against
+    # a schema.
+    class Checker
+      # Creates a new {Checker} using a {Schema} object.
+      def initialize(schema)
+        self.schema = schema
+      end
+
+      # Checks iteratively through an array of objects.
       def check_array!(array)
         array.each { |item| check!(item) }
       end
 
+      # Checks if an object follows the contract provided by
+      # the schema. This will just pass through if everything is ok.
+      # If something is wrong, an error will be raised. The actual check
+      # will be done, attribute by attribute, by an instance of {ObjectChecker},
+      # calling the methods {ObjectChecker#check_missed_key! check_missed_key!} and
+      # {ObjectChecker#check_invalid! check_invalid!}.
+      #
+      # @param object [Hash] the object to check against the schema.
+      # @raise NoObjectError if parameter passed is not a hash.
       def check!(object)
         raise NoObjectError.new(object) unless object.is_a?(Hash)
 
         schema.attributes.each do |_, attribute|
           if attribute.can_be_checked?
             checker = ObjectChecker.new(object, attribute)
-
-            raise NoAttributeError.new(object, attribute) if checker.missed_key?
-            raise DifferentTypeError.new(object, attribute) if checker.wrong_type?
+            checker.check_missed_key!
+            checker.check_invalid!
           end
         end
       end
 
       private
 
-      class ObjectChecker < Struct.new(:object, :attribute)
+      attr_accessor :schema
+
+      # Checks an object against a schema's attribute
+      # definition.
+      class ObjectChecker
+        def initialize(object, attribute)
+          self.object = object
+          self.attribute = attribute
+        end
+
+        # Checks if the attribute's key is absent from the object.
+        #
+        # @example
+        #   # Given the following schema
+        #   schema :product do
+        #     attribute :name, string
+        #   end
+        #
+        #   ObjectChecker.new({ age: 10 }, schema.attributes[:name]).missed_key?
+        #   # true
+        #   ObjectChecker.new({ name: 'John' }, schema.attributes[:name]).missed_key?
+        #   # false
+        #
+        # @return [true, false] If the attribute's key is absent from the object
         def missed_key?
           !object.has_key?(attribute.name)
         end
 
-        def wrong_type?
+        # Calls {#missed_key?} and if the call is true, raises
+        # a {NoAttributeError}.
+        def check_missed_key!
+          raise NoAttributeError.new(object, attribute) if missed_key?
+        end
+
+        # Checks if the attribute's type validation fails
+        # with the object' attribute. To do this, the #valid? method
+        # of the type is executed.
+        #
+        # @example
+        #   # Given the following schema
+        #   schema :product do
+        #     attribute :name, string
+        #   end
+        #
+        #   ObjectChecker.new({ name: 10 }, schema.attributes[:name]).invalid?
+        #   # true
+        #   ObjectChecker.new({ name: 'John' }, schema.attributes[:name]).invalid?
+        #   # false
+        #
+        # @return [true, false] If the attribute's type validation fails
+        #   with the object' attribute.
+        def invalid?
           !attribute.type.totally_valid?(attribute, object.fetch(attribute.name))
         end
+
+        # Calls {#invalid?} and if the call is true, raises
+        # a {InvalidationError}.
+        def check_invalid!
+          raise InvalidationError.new(object, attribute) if invalid?
+        end
+
+        private
+
+        attr_accessor :object, :attribute
       end
 
       class NoAttributeError < StandardError
@@ -43,7 +115,7 @@ module Restspec
         end
       end
 
-      class DifferentTypeError < StandardError
+      class InvalidationError < StandardError
         attr_accessor :object, :attribute, :value
 
         def initialize(object, attribute)
@@ -53,7 +125,7 @@ module Restspec
         end
 
         def to_s
-          "The property #{attribute.name} of #{object} should be of type #{attribute.type} but it was of type #{value.class}"
+          "The property #{attribute.name} of #{object} was not valid according to the type #{attribute.type}"
         end
       end
 

data/lib/restspec/schema/dsl.rb

@@ -1,50 +1,106 @@
 module Restspec
   module Schema
+    # The Schema DSL is what should be used inside the `schemas.rb` file.
+    # This class is related to the top-level namespace of the DSL.
     class DSL
-      attr_reader :schemas
-      attr_accessor :mixins
-
       def initialize
         self.mixins = {}
       end
 
+      # Generates a schema and sends the schema to an {SingleSchemaDSL}
+      # instance for further definitions.
+      #
+      # @example
+      #   schema :book do
+      #     puts self.class # SingleSchemaDSL
+      #     puts self.schema.class # Schema
+      #   end
+      #
+      # @param name {Symbol} the schema's name
+      # @param definition A block that will be executed inside the context
+      #   of a {SingleSchemaDSL} object.
       def schema(name, &definition)
         dsl = SingleSchemaDSL.new(name, mixins)
         dsl.instance_eval(&definition)
         Restspec::SchemaStore.store(dsl.schema)
       end
 
+      # Generates a set of calls that can be executed in
+      # many schemas with {SingleSchemaDSL#include_attributes}.
+      #
+      # They are useful to share attributes.
+      #
+      # @example
+      #
+      #   mixin :timestamps do
+      #     attribute :created_at, date
+      #     attribute :updated_at, date
+      #   end
+      #
+      #   schema :book do
+      #     include_attributes :timestamps
+      #   end
+      #
+      #   schema :celphones do
+      #     include_attributes :timestamps
+      #   end
+      #
+      # @param name {Symbol} the mixin's name
+      # @param definition A block that will be executed on demand
+      #   in an {SingleSchemaDSL} object's context.
       def mixin(name, &definition)
         mixins[name] = definition
       end
+
+      private
+
+      attr_accessor :mixins
     end
 
+    # The DSL to use inside `schema` and `mixin` blocks of
+    # a {DSL} instance block. It defines specific things of a
+    # schema or a group of them.
     class SingleSchemaDSL
-      attr_reader :schema, :mixins
+      include Types::TypeMethods
+
+      # @return {Schema} the current schema
+      attr_reader :schema
 
       def initialize(name, mixins = {})
         self.schema = Schema.new(name)
         self.mixins = mixins
       end
 
+      # Creates an attribute and saving it into the schema.
+      # It uses the same parameters as the {Attribute#initialize} method.
+      #
+      # @example
+      #
+      #  schema :books do
+      #   attribute :title, string
+      #   attribute :created_at, datetime, :for => [:checks]
+      #  end
+      #
+      # @param (see Attribute#initialize)
       def attribute(name, type, options = {})
         new_attribute = Attribute.new(name, type, options)
         schema.attributes[name.to_s] = new_attribute
       end
 
+      # Includes a mixin generated by the {DSL#mixin} function
+      # into the schema.
+      #
+      # @example (see DSL#mixin)
+      #
+      # @param name [Symbol] the mixin name
       def include_attributes(name)
         self.instance_eval &mixins.fetch(name)
       end
 
-      Types::ALL.each do |type_name, type_class|
-        define_method(type_name) do |options = {}|
-          type_class.new(options)
-        end
-      end
-
       private
 
-      attr_writer :schema, :mixins
+      attr_writer :schema
+      attr_accessor :mixins
     end
   end
 end

data/lib/restspec/schema/schema.rb

@@ -1,13 +1,25 @@
 module Restspec
   module Schema
+    # A schema is a collection of attributes that defines how the data passed through the API
+    # should be formed. In REST, they are the representation of the resources the REST API
+    # returns.
     class Schema
-      attr_reader :name, :attributes
+      # The schema identifier.
+      attr_reader :name
 
+      # The set of attributes that conforms the schema.
+      attr_reader :attributes
+
+      # @param name [Symbol] The name of the schema
+      # @return a new {Restspec::Schema::Schema Schema} object
       def initialize(name)
         self.name = name
         self.attributes = {}
       end
 
+      # @param without [Array] An array of attributes that should be removed from the schema.
+      #   This shouldn't be used without cloning first, to avoid modifying a schema
+      #   used elsewhere.
       def extend_with(without: [])
         without.each { |attribute_name| attributes.delete(attribute_name.to_s) }
         self

data/lib/restspec/schema/schema_example.rb

@@ -1,13 +1,19 @@
 module Restspec
   module Schema
+    # A value object that generates a example from a schema using an optional set of extensions.
     class SchemaExample
-      attr_accessor :schema, :extensions
+      attr_accessor :schema
+      attr_accessor :extensions
 
+      # @param schema [Restspec::Schema::Schema] the schema used to generate the example.
+      # @param extensions [Hash] A set of extensions to merge with the example.
       def initialize(schema, extensions = {})
         self.schema = schema
         self.extensions = extensions
       end
 
+      # It returns the generated example.
+      # @return [Restspec::Values::SuperHash] generated example.
       def value
         attributes.inject({}) do |sample, (_, attribute)|
           if attribute.can_generate_examples?

data/lib/restspec/schema/types/array_type.rb

@@ -1,5 +1,31 @@
 module Restspec::Schema::Types
   class ArrayType < BasicType
+    # Generates an example array.
+    #
+    # @example without a parameterized type
+    #   # schema
+    #   attribute :name, array
+    #   # examples
+    #   example_for(schema.attributes[:name])
+    #   # => []
+    #
+    # @example with a parameterized type and no length example option
+    #   # schema
+    #   attribute :name, array.of(string)
+    #   # examples
+    #   example_for(schema.attributes[:name])
+    #   # => ['hola', 'mundo'] # the length is something randomly between 1 a 5.
+    #
+    # @example with a parameterized type and length example option
+    #   # schema
+    #   attribute :name, array(length: 2).of(string) # or:
+    #   attribute :name, array(example_options: { length: 2}).of(string)
+    #   # examples
+    #   example_for(schema.attributes[:name])
+    #   # => ['hola', 'mundo'] # the length will always be 2
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @return [Array] Generated array for examples.
     def example_for(attribute)
       length_only_works_with_parameterized_types!
 
@@ -8,6 +34,16 @@ module Restspec::Schema::Types
       end
     end
 
+    # Validates if the array is valid.
+    #
+    # - Without a parameterized type, it only checks if the value is an array.
+    # - With a parameterized type, it checks is every object inside the array
+    #   is valid against the parameterized type.
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @param value [Object] the value of the attribute.
+    #
+    # @return [true, false] If the array is valid.
     def valid?(attribute, value)
       is_array = value.is_a?(Array)
       if parameterized_type
@@ -22,7 +58,12 @@ module Restspec::Schema::Types
     private
 
     def example_length
-      example_options.fetch(:length, 0)
+      example_options.fetch(:length, internal_length)
+    end
+
+    def internal_length
+      return 0 if !parameterized_type
+      rand(1..5)
     end
 
     def length_only_works_with_parameterized_types!

data/lib/restspec/schema/types/basic_type.rb

@@ -1,18 +1,72 @@
+# This is the parent class for all the Types used in the schemas definition.
+# The two main reasons of the inheritance over simple duck typing are:
+#
+#   1. To force the usage of `example_options` and `schema_options`, different
+#     sets of options for the two cases a type is used. This two methods are only used
+#     privately by the subclasses.
+#   2. To allow some kind of **'type algebra'**, with the {#|}, {#of} and {#totally_valid?} methods.
 class Restspec::Schema::Types::BasicType
   def initialize(options = {})
     self.options = options
   end
 
+  # The disjunction operator (||) is not a method in ruby, so we are using `|`
+  # because it looks similar. The important thing about the type disjunction is
+  # that, when checking through a type, a value can checks itself against
+  # multiple possible types.
+  #
+  # @example with two types
+  #   attribute :name, string | null
+  #
+  #   attr_type = schema.attributes[:name].type
+  #   attr_type.totally_valid?(schema.attributes[:name], 'Hola') # true
+  #   attr_type.totally_valid?(schema.attributes[:name], nil) # true
+  #   attr_type.totally_valid?(schema.attributes[:name], 10) # false
+  #
+  # The example works because the type returned by `string | null` is basically
+  # just `string` with a disjunction set to `null`. When validating, if the validation
+  # fails initially, the disjunction is used as a second source of thuth. Because the
+  # disjunction can have disjunctions too, we can test against more than two types.
+  #
+  # @example with more than two types
+  #   attribute :name, string | (null | integer)
+  #
+  #   attr_type = schema.attributes[:name].type
+  #   attr_type.totally_valid?(schema.attributes[:name], 'Hola') # true
+  #   attr_type.totally_valid?(schema.attributes[:name], nil) # true
+  #   attr_type.totally_valid?(schema.attributes[:name], 10) # true
+  #
+  # @param other_type [instance of subclass of BasicType] the type to make the disjuction.
+  # @return [BasicType] the same object that is used to call the method. (`self`)
   def |(other_type)
     self.disjuction = other_type
     self
   end
 
+  # The only work of `of` is to set a `parameterized_type` attribute
+  # on the type. This parameterized type can be used by the type itself to
+  # whatever the type wants. The major limitation is that, by now, we only
+  # allow one parameterized type. For example, {ArrayType} uses this parameterized
+  # type to do this:
+  #
+  # @example
+  #   attribute :codes, array.of(integer)
+  #
+  # @param other_type [instance of subclass of BasicType] the type to make the
+  #   save as the parameterized type.
+  # @return [BasicType] the same object that is used to call the method. (`self`)
   def of(other_type)
     self.parameterized_type = other_type
     self
   end
 
+  # This calls the `valid?` method (that is not present in this class but should
+  # be present on their children) making sure to fallback to the disjunction if
+  # the disjunction is present.
+  #
+  # @param attribute [Restspec::Schema::Attribute] The attribute to use.
+  # @param value [Object] the object that holds the actual value to test against.
+  # @return [true, false] If the type is valid with the following attribute and value.
   def totally_valid?(attribute, value)
     if disjuction.present?
       valid?(attribute, value) || disjuction.valid?(attribute, value)
@@ -21,6 +75,14 @@ class Restspec::Schema::Types::BasicType
     end
   end
 
+  # @return [String] a string representation of the type. It's basically the
+  #   class name without the `Type` postfix underscorized.
+  #
+  # @example
+  #
+  #   StringType.new.to_s #=> string
+  #   ArrayType.new.to_s #=> array
+  #   SchemaIdType.new.to_s #=> schema_id
   def to_s
     self.class.name.demodulize.gsub(/Type$/, "").underscore
   end

data/lib/restspec/schema/types/boolean_type.rb

@@ -1,9 +1,19 @@
 module Restspec::Schema::Types
   class BooleanType < BasicType
+    # Generates an example boolean.
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @return [true, false] One of `true` and `false`, randomly.
     def example_for(attribute)
       [true, false].sample
     end
 
+    # Validates is the value is a boolean.
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @param value [Object] the value of the attribute.
+    #
+    # @return [true, false] If the value is one of true and false.
     def valid?(attribute, value)
       [true, false].include?(value)
     end

data/lib/restspec/schema/types/date_type.rb

@@ -2,10 +2,22 @@ module Restspec::Schema::Types
   class DateType < BasicType
     DATE_FORMAT = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/
 
+    # Generates an example date.
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @return [Date] A random date between one month ago and today.
     def example_for(attribute)
       Faker::Date.between(1.month.ago, Date.today).to_s
     end
 
+    # Validates if the value is a date.
+    # It basically checks if the date is according
+    # to yyyy-mm-dd format
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @param value [Object] the value of the attribute.
+    #
+    # @return [true, false] If the value is a date with the correct format.
     def valid?(attribute, value)
       return false unless value.present?
       return false unless value.match(DATE_FORMAT).present?