jsapi 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 162f63ee5ef06ba76a2acb100e92928144533e8d2486175b95cf4f8a38d6f93d
-  data.tar.gz: bf6579a80a1bdc8eb2ab3ca7921f42f1a68466508425568e3c5b984e7e1b34b8
+  metadata.gz: cb2e35d1d98201647ee5ec6087437891fc7781e94c717804275a6ed1ee870267
+  data.tar.gz: 1295f4128a5e096e64be1243f532ada34a58032860b87515836697ee48c7a51f
 SHA512:
-  metadata.gz: 71c6b38cb010530b4b6f4cfebee131981c2874114bf663287739452f709863e64e073b358dded464ee86d2d14ce68439170e15c709667d1098a804f874728cd3
-  data.tar.gz: 8e60c31c91af85df15c2bb9c2c0a17fa67599df3621c90603bbe624615a6749e3a909b1a8e91cb5ea5a7aab8d75ee03adaf32ea28e4abd95d30bc7fd1cadd754
+  metadata.gz: 0f826bdf8be20affd8181feaf0f507705cf87ab9960711e1715dd4b2a7abb6ba072654532e99a7701359b8a38685f80c19aa39be1e0538f27befd460a8c8c74c
+  data.tar.gz: fbd3593855e17a5e6621e572ed292073d5849f802dc39febbb20d59e0f2a3133118cbc1c84413f8cfbd4a17047d28b5989a476abe8904f6a0c2f8390abda4dbf

data/lib/jsapi/controller/methods.rb

@@ -13,9 +13,9 @@ module Jsapi
       end
 
       # Performs an API operation by calling the given block. The request parameters are
-      # passed as an instance of the operation's model class to the block. Parameter names
-      # are converted to snake case. The object returned by the block is implicitly rendered
-      # according to the appropriate +response+ specification.
+      # passed as an instance of the operation's model class to the block. The object
+      # returned by the block is implicitly rendered according to the appropriate +response+
+      # specification.
       #
       #   api_operation('foo') do |api_params|
       #     # ...
@@ -23,13 +23,22 @@ module Jsapi
       #
       # +operation_name+ can be +nil+ if the controller handles one operation only.
       #
-      # If +strong+ is +true+, parameters that can be mapped are accepted only. That means
+      # If +:strong+ is +true+, parameters that can be mapped are accepted only. That means
       # that the model passed to the block is invalid if there are any request parameters
       # that can't be mapped to a parameter or a request body property of the operation.
       #
-      def api_operation(operation_name = nil, status: nil, strong: false, &block)
+      # The +:omit+ option specifies on which conditions properties are omitted.
+      # Possible values are:
+      #
+      # - +:empty+ - All of the  properties whose value is empty are omitted.
+      # - +:nil+ - All of the properties whose value is +nil+ are omitted.
+      #
+      # Raises an InvalidArgumentError when the value of +:omit+ is invalid.
+      def api_operation(operation_name = nil, omit: nil, status: nil, strong: false, &block)
         _perform_api_operation(
-          operation_name, false,
+          operation_name,
+          bang: false,
+          omit: omit,
           status: status,
           strong: strong,
           &block
@@ -43,9 +52,11 @@ module Jsapi
       #     # ...
       #   end
       #
-      def api_operation!(operation_name = nil, status: nil, strong: false, &block)
+      def api_operation!(operation_name = nil, omit: nil, status: nil, strong: false, &block)
         _perform_api_operation(
-          operation_name, true,
+          operation_name,
+          bang: true,
+          omit: omit,
           status: status,
           strong: strong,
           &block
@@ -79,12 +90,20 @@ module Jsapi
       #   render(json: api_response(bar, 'foo', status: 200))
       #
       # +operation_name+ can be +nil+ if the controller handles one operation only.
-      def api_response(result, operation_name = nil, status: nil)
+      #
+      # The +:omit+ option specifies on which conditions properties are omitted.
+      # Possible values are:
+      #
+      # - +:empty+ - All of the  properties whose value is empty are omitted.
+      # - +:nil+ - All of the properties whose value is +nil+ are omitted.
+      #
+      # Raises an InvalidArgumentError when the value of +:omit+ is invalid.
+      def api_response(result, operation_name = nil, omit: nil, status: nil)
         definitions = api_definitions
         operation = _api_operation(operation_name, definitions)
         response = _api_response(operation, status, definitions)
 
-        Response.new(result, response, api_definitions)
+        Response.new(result, response, api_definitions, omit: omit)
       end
 
       private
@@ -98,7 +117,13 @@ module Jsapi
 
       def _api_params(operation, definitions, strong:)
         (operation.model || Model::Base).new(
-          Parameters.new(params, operation, definitions, strong: strong)
+          Parameters.new(
+            params.except(:action, :controller, :format).permit!,
+            headers,
+            operation,
+            definitions,
+            strong: strong
+          )
         )
       end
 
@@ -109,7 +134,7 @@ module Jsapi
         raise "status code not defined: #{status}"
       end
 
-      def _perform_api_operation(operation_name, bang, status:, strong:, &block)
+      def _perform_api_operation(operation_name, bang:, omit:, status:, strong:, &block)
         definitions = api_definitions
         operation = _api_operation(operation_name, definitions)
         response = _api_response(operation, status, definitions)
@@ -141,10 +166,11 @@ module Jsapi
 
             ErrorResult.new(e, status: status)
           end
-          render(json: Response.new(result, response, definitions), status: status)
+          render(json: Response.new(result, response, definitions, omit: omit), status: status)
         else
           head(status)
         end
+        self.content_type = response.content_type
       end
     end
   end

data/lib/jsapi/controller/parameters.rb

@@ -6,7 +6,7 @@ module Jsapi
     class Parameters
       include Model::Nestable
 
-      attr_reader :raw_attributes
+      attr_reader :raw_additional_attributes, :raw_attributes
 
       # Creates a new instance that wraps +params+ according to +operation+. References are
       # resolved to API components in +definitions+.
@@ -14,29 +14,35 @@ module Jsapi
       # If +strong+ is true+ parameters that can be mapped are accepted only. That means that
       # the instance created is invalid if +params+ contains any parameters that can't be
       # mapped to a parameter or a request body property of +operation+.
-      def initialize(params, operation, definitions, strong: false)
-        @params = params
+      def initialize(params, headers, operation, definitions, strong: false)
+        @params = params.to_h
         @strong = strong == true
         @raw_attributes = {}
+        @raw_additional_attributes = {}
 
-        # Merge parameters and request body properties
-        meta_models = operation.parameters.transform_values do |parameter|
-          parameter.resolve(definitions)
-        end
-        request_body = operation.request_body&.resolve(definitions)
-        if request_body && request_body.schema.respond_to?(:properties)
-          meta_models.merge!(request_body.schema.resolve_properties(:write, definitions))
-        end
+        # Parameters
+        operation.parameters.each do |name, parameter_model|
+          parameter_model = parameter_model.resolve(definitions)
 
-        # Wrap params
-        meta_models.each do |name, meta_model|
-          @raw_attributes[name.underscore] = JSON.wrap(params[name], meta_model.schema, definitions)
+          @raw_attributes[name] = JSON.wrap(
+            parameter_model.in == 'header' ? headers[name] : @params[name],
+            parameter_model.schema.resolve(definitions),
+            definitions
+          )
         end
-      end
 
-      def inspect # :nodoc:
-        "#<#{self.class.name} " \
-        "#{attributes.map { |k, v| "#{k}: #{v.inspect}" }.join(', ')}>"
+        # Request body
+        request_body_schema = operation.request_body&.resolve(definitions)
+                                       &.schema&.resolve(definitions)
+        if request_body_schema&.object?
+          request_body = JSON.wrap(
+            @params.except(*operation.parameters.keys),
+            request_body_schema,
+            definitions
+          )
+          @raw_attributes.merge!(request_body.raw_attributes)
+          @raw_additional_attributes = request_body.raw_additional_attributes
+        end
       end
 
       # Validates the request parameters. Returns true if the parameters are valid, false
@@ -44,11 +50,7 @@ module Jsapi
       def validate(errors)
         [
           validate_attributes(errors),
-          !@strong || validate_parameters(
-            @params.except(:controller, :action, :format),
-            attributes,
-            errors
-          )
+          !@strong || validate_parameters(@params, attributes, errors)
         ].all?
       end
 

data/lib/jsapi/controller/response.rb

@@ -7,10 +7,23 @@ module Jsapi
 
       # Creates a new instance to serialize +object+ according to +response+. References
       # are resolved to API components in +definitions+.
-      def initialize(object, response, definitions)
+      #
+      # The +:omit+ option specifies on which conditions properties are omitted.
+      # Possible values are:
+      #
+      # - +:empty+ - All of the  properties whose value is empty are omitted.
+      # - +:nil+ - All of the properties whose value is +nil+ are omitted.
+      #
+      # Raises an InvalidArgumentError when the value of +:omit+ is invalid.
+      def initialize(object, response, definitions, omit: nil)
+        if [:empty, :nil, nil].exclude?(omit)
+          raise InvalidArgumentError.new('omit', omit, valid_values: %i[empty nil])
+        end
+
         @object = object
         @response = response
         @definitions = definitions
+        @omit = omit
       end
 
       def inspect # :nodoc:
@@ -32,7 +45,9 @@ module Jsapi
       private
 
       def serialize(object, schema, path = nil)
+        object = schema.default_value(@definitions, context: :response) if object.nil?
         return if object.nil? && schema.nullable?
+
         raise "#{path || 'response'} can't be nil" if object.nil?
 
         case schema.type
@@ -68,36 +83,33 @@ module Jsapi
       end
 
       def serialize_object(object, schema, path)
-        return if object.blank? # {}
-
-        # Select inherriting schema on polymorphism
-        if (discriminator = schema.discriminator)
-          discriminator_property = schema.properties[discriminator.property_name]
-          schema = discriminator.resolve(
-            object.public_send(discriminator_property.source || discriminator_property.name.underscore),
-            @definitions
-          )
-        end
+        schema = schema.resolve_schema(object, @definitions, context: :response)
+        properties = {}
+
         # Serialize properties
-        properties = schema.resolve_properties(:read, @definitions).transform_values do |property|
-          serialize(
-            if (method_chain = property.source).present?
-              method_chain.call(object)
-            else
-              object.public_send(property.name.underscore)
-            end,
-            property.schema.resolve(@definitions),
+        schema.resolve_properties(@definitions, context: :response).each do |key, property|
+          property_schema = property.schema.resolve(@definitions)
+          property_value = property.reader.call(object)
+          property_value = property_schema.default if property_value.nil?
+
+          next if ((@omit == :empty && property_value.try(:empty?)) ||
+                   (@omit == :nil && property_value.nil?)) &&
+                  property_schema.omittable?
+
+          properties[key] = serialize(
+            property_value,
+            property_schema,
             path.nil? ? property.name : "#{path}.#{property.name}"
           )
         end
-        if (additional_properties = schema.additional_properties&.resolve(@definitions))
+        # Serialize additional properties
+        if (additional_properties = schema.additional_properties)
           additional_properties_schema = additional_properties.schema.resolve(@definitions)
 
           additional_properties.source.call(object)&.each do |key, value|
             # Don't replace the property with the same key
             next if properties.key?(key = key.to_s)
 
-            # Serialize the additional property
             properties[key] = serialize(
               value,
               additional_properties_schema,
@@ -105,7 +117,8 @@ module Jsapi
             )
           end
         end
-        properties
+        # Return properties if present, otherwise nil
+        properties if properties.present?
       end
     end
   end

data/lib/jsapi/dsl/class_methods.rb

@@ -3,6 +3,14 @@
 module Jsapi
   module DSL
     module ClassMethods
+      # Specifies the general default values for +type+.
+      #
+      #   api_default 'array', read: [], write: []
+      #
+      def api_default(type, **keywords, &block)
+        api_definitions { default(type, **keywords, &block) }
+      end
+
       # The API definitions of the current class.
       def api_definitions(&block)
         @api_definitions ||= Meta::Definitions.new(self)
@@ -30,24 +38,24 @@ module Jsapi
       #   end
       #
       # +name+ can be +nil+ if the controller handles one operation only.
-      def api_operation(name = nil, **options, &block)
-        api_definitions { operation(name, **options, &block) }
+      def api_operation(name = nil, **keywords, &block)
+        api_definitions { operation(name, **keywords, &block) }
       end
 
       # Defines a reusable parameter.
       #
       #   api_parameter 'foo', type: 'string'
       #
-      def api_parameter(name, **options, &block)
-        api_definitions { parameter(name, **options, &block) }
+      def api_parameter(name, **keywords, &block)
+        api_definitions { parameter(name, **keywords, &block) }
       end
 
       # Defines a reusable request body.
       #
       #   api_request_body 'foo', type: 'string'
       #
-      def api_request_body(name, **options, &block)
-        api_definitions { request_body(name, **options, &block) }
+      def api_request_body(name, **keywords, &block)
+        api_definitions { request_body(name, **keywords, &block) }
       end
 
       # Specifies the HTTP status code of an error response rendered when an
@@ -64,8 +72,8 @@ module Jsapi
       #   api_response 'Foo', type: 'object' do
       #     property 'bar', type: 'string'
       #   end
-      def api_response(name, **options, &block)
-        api_definitions { response(name, **options, &block) }
+      def api_response(name, **keywords, &block)
+        api_definitions { response(name, **keywords, &block) }
       end
 
       # Defines a reusable schema.
@@ -73,8 +81,8 @@ module Jsapi
       #   api_schema 'Foo' do
       #     property 'bar', type: 'string'
       #   end
-      def api_schema(name, **options, &block)
-        api_definitions { schema(name, **options, &block) }
+      def api_schema(name, **keywords, &block)
+        api_definitions { schema(name, **keywords, &block) }
       end
 
       # Defines the root of an OpenAPI document.

data/lib/jsapi/dsl/definitions.rb

@@ -5,6 +5,17 @@ module Jsapi
     # Used to define top-level API components.
     class Definitions < Node
 
+      # Specifies the general default values for +type+.
+      #
+      #   default 'array', read: [], write: []
+      #
+      def default(type, **keywords, &block)
+        _define('default', type.inspect) do
+          default = _meta_model.add_default(type, keywords)
+          Node.new(default, &block) if block
+        end
+      end
+
       # Includes API definitions from +klasses+.
       def include(*klasses)
         klasses.each do |klass|

data/lib/jsapi/dsl/openapi/callbacks.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module DSL
+    module OpenAPI
+      module Callbacks
+        # Defines an \OpenAPI callback or refers a reusable callback.
+        #
+        #   # define a callback
+        #   callback 'foo' do
+        #     operation '{$request.query.foo}'
+        #   end
+        #
+        #   # refer a reusable callback
+        #   callback ref: 'foo'
+        #
+        # Refers the reusable callback with the same name if neither any
+        # keywords nor a block is specified.
+        #
+        #   callback 'foo'
+        #
+        def callback(name = nil, **keywords, &block)
+          _define('callback', name&.inspect) do
+            name = keywords[:ref] if name.nil?
+            keywords = { ref: name } unless keywords.any? || block
+
+            callback_model = _meta_model.add_callback(name, keywords)
+            _eval(callback_model, OpenAPI::Callback, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/dsl/openapi/examples.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module DSL
+    module OpenAPI
+      module Examples
+        # Adds an example.
+        #
+        #   example 'foo', value: 'bar'
+        #
+        #   example 'foo'
+        #
+        # The default name is <code>'default'</code>.
+        def example(name_or_value = nil, **keywords, &block)
+          _define('example', name_or_value&.inspect) do
+            if keywords.any? || block
+              # example 'foo', value: 'bar', ...
+              name = name_or_value
+            else
+              # example 'foo'
+              name = nil
+              keywords = { value: name_or_value }
+            end
+
+            example = _meta_model.add_example(name, keywords)
+            Node.new(example, &block) if block
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/dsl/openapi.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'openapi/callbacks'
+require_relative 'openapi/examples'
 require_relative 'openapi/callback'
 require_relative 'openapi/root'

data/lib/jsapi/dsl/operation.rb

@@ -4,7 +4,7 @@ module Jsapi
   module DSL
     # Used to specify details of an operation.
     class Operation < Node
-      include Callbacks
+      include OpenAPI::Callbacks
 
       ##
       # :method: deprecated

data/lib/jsapi/dsl/parameter.rb

@@ -4,7 +4,7 @@ module Jsapi
   module DSL
     # Used to specify details of a parameter.
     class Parameter < Schema
-      include Examples
+      include OpenAPI::Examples
 
       ##
       # :method: deprecated

data/lib/jsapi/dsl/request_body.rb

@@ -4,7 +4,7 @@ module Jsapi
   module DSL
     # Used to specify details of a request body.
     class RequestBody < Schema
-      include Examples
+      include OpenAPI::Examples
 
       ##
       # :method: deprecated

data/lib/jsapi/dsl/response.rb

@@ -4,7 +4,7 @@ module Jsapi
   module DSL
     # Used to specify details of a response.
     class Response < Schema
-      include Examples
+      include OpenAPI::Examples
 
       ##
       # :method: deprecated

data/lib/jsapi/dsl.rb

@@ -1,15 +1,13 @@
 # frozen_string_literal: true
 
-require_relative 'dsl/callbacks'
-require_relative 'dsl/examples'
 require_relative 'dsl/error'
 require_relative 'dsl/node'
+require_relative 'dsl/openapi'
 require_relative 'dsl/schema'
 require_relative 'dsl/parameter'
 require_relative 'dsl/request_body'
 require_relative 'dsl/response'
 require_relative 'dsl/operation'
-require_relative 'dsl/openapi'
 require_relative 'dsl/definitions'
 require_relative 'dsl/class_methods'
 

data/lib/jsapi/helpers/invalid_value_helper.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module InvalidValueHelper
+    def build_message(name, value, valid_values)
+      case valid_values.count
+      when 0
+        "#{name} must not be #{value.inspect}"
+      when 1
+        "#{name} must be #{valid_values.first.inspect}, is #{value.inspect}"
+      else
+        "#{name} must be one of #{valid_values[0..-2].map(&:inspect).join(', ')} " \
+        "or #{valid_values.last.inspect}, is #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/jsapi/invalid_argument_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Jsapi
+  # Raised when an argument isn't contained in the list of valid values.
+  class InvalidArgumentError < ArgumentError
+    include InvalidValueHelper
+
+    def initialize(name, value, valid_values: [])
+      super(build_message(name, value, valid_values))
+    end
+  end
+end

data/lib/jsapi/invalid_value_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Jsapi
+  # Raised when a value isn't contained in the list of valid values.
+  class InvalidValueError < RuntimeError
+    include InvalidValueHelper
+
+    def initialize(name, value, valid_values: [])
+      super(build_message(name, value, valid_values))
+    end
+  end
+end

data/lib/jsapi/json/object.rb

@@ -6,18 +6,24 @@ module Jsapi
     class Object < Value
       include Model::Nestable
 
-      attr_reader :raw_attributes
+      attr_reader :raw_additional_attributes, :raw_attributes
 
       def initialize(attributes, schema, definitions)
-        # Select inherriting schema on polymorphism
-        if (discriminator = schema.discriminator)
-          schema = discriminator.resolve(attributes[discriminator.property_name], definitions)
+        schema = schema.resolve_schema(attributes, definitions, context: :request)
+        properties = schema.resolve_properties(definitions, context: :request)
+
+        @raw_attributes = properties.transform_values do |property|
+          JSON.wrap(attributes[property.name], property.schema, definitions)
         end
-        # Wrap attribute values
-        @raw_attributes =
-          schema.resolve_properties(:write, definitions).transform_values do |property|
-            JSON.wrap(attributes[property.name], property.schema, definitions)
-          end
+
+        @raw_additional_attributes =
+          if (additional_properties = schema.additional_properties)
+            additional_properties_schema = additional_properties.schema.resolve(definitions)
+
+            attributes.except(*properties.keys).transform_values do |value|
+              JSON.wrap(value, additional_properties_schema, definitions)
+            end
+          end || {}
 
         super(schema)
       end
@@ -27,11 +33,6 @@ module Jsapi
         @raw_attributes.values.all?(&:empty?)
       end
 
-      def inspect # :nodoc:
-        "#<#{self.class.name} " \
-        "#{@raw_attributes.map { |k, v| "#{k}: #{v.inspect}" }.join(', ')}>"
-      end
-
       # Returns a model to read attributes by.
       def model
         @model ||= (schema.model || Model::Base).new(self)

data/lib/jsapi/json.rb

@@ -16,7 +16,7 @@ module Jsapi
       def wrap(object, schema, definitions = nil)
         schema = schema.resolve(definitions) unless definitions.nil?
 
-        object = schema.default if object.nil?
+        object = schema.default_value(definitions, context: :request) if object.nil?
         return Null.new(schema) if object.nil?
 
         case schema.type

data/lib/jsapi/meta/{attributes/class_methods.rb → base/attributes.rb}

@@ -2,8 +2,8 @@
 
 module Jsapi
   module Meta
-    module Attributes
-      module ClassMethods
+    module Base
+      module Attributes
         # Defines an attribute.
         def attribute(name, type = Object,
                       keys: nil,