jsapi 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d672ecea7da1c27309fe576ceacc537286529da833a37726f8e34299b33d7d48
-  data.tar.gz: 9d2d663c47dc498def2c9ce60b73029bfba52a0a2b15690e4a41b4a0bed3d70a
+  metadata.gz: 49b5e17933d1306b3c7637f0d0dd37d3efb7f698acc43b0664c239d6caf4b593
+  data.tar.gz: '08b7e251c989693f2d055c140488278d2c2fb047a814fe4ff90be7fdb2fa8869'
 SHA512:
-  metadata.gz: 241798754adbc58ad39ecf1d238977ec5b7bba2f557b2d4fd5190eb9cc4b14db5afeeb61cc48a6e1435be03178b95e0728deaa4d5afa3b58758becc765ee9105
-  data.tar.gz: b8823805ad8cf8d09dd72a8ef930086bcb3f4554ad9f868f7a6554062f263bd450fe14f01f21fbfb58b47577681d86a8fd9e5655a0ed522833e223c7478a278e
+  metadata.gz: ba696113c7b4e842085baa0ad4462a5566c7b5fb8c96030708eb4e33b47319865d86271d1f4b6643a39e83c7a59ee71c54b7d3ca6837e9515e6665d94e1ff7d2
+  data.tar.gz: 9f0e9aa79495064cdbebdfd12cbdd4501891ef5c5be30ffe3a0435afa58fd7ec87750eeb5c9068ff4da49a17e56c2e028512a260155ed2f0f13b4fde88cd23a4

data/lib/jsapi/controller/error_result.rb

@@ -2,19 +2,26 @@
 
 module Jsapi
   module Controller
-    # Used by +api_operation!+ to produce an error response.
+    # Used by Methods#api_operation! to produce an error response.
     class ErrorResult
+      delegate_missing_to :@exception
 
       # The HTTP status code of the error response to be produced.
       attr_reader :status
 
-      delegate :message, :to_s, to: :@exception
-
       # Creates a new instance to produce an error response with the given HTTP status code.
-      def initialize(exception, status:)
+      def initialize(exception, status: nil)
         @exception = exception
         @status = status
       end
+
+      # Returns the string representation of the exception encountered to render this string
+      # when the response type is +string+, for example:
+      #
+      #   response 500, type: 'string'
+      def to_s
+        @exception.to_s
+      end
     end
   end
 end

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/parameters_invalid.rb

@@ -2,8 +2,10 @@
 
 module Jsapi
   module Controller
-    # Raised by Methods#api_operation! if the request parameters are invalid.
+    # Raised by Methods#api_operation! when the request parameters are invalid.
     class ParametersInvalid < StandardError
+
+      # The parameters.
       attr_reader :params
 
       def initialize(params)
@@ -11,13 +13,14 @@ module Jsapi
         super('')
       end
 
-      # Overrides <code>StandardError#message</code> to lazily generate the error message.
+      # Returns the errors encountered.
+      def errors
+        @params.errors.errors
+      end
+
+      # Overrides <code>Exception#message</code> to lazily generate the error message.
       def message
-        "#{
-          @params.errors.full_messages.map do |message|
-            message.delete_suffix('.')
-          end.join('. ')
-        }."
+        "#{@params.errors.full_messages.map { |m| m.delete_suffix('.') }.join('. ')}."
       end
     end
   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,32 +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(
-            object.public_send(property.source || property.name.underscore),
-            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.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)
 
-          object.public_send(additional_properties.source)&.each do |key, value|
+          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,
@@ -101,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)