jsapi 0.7.3 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0b8caebf611ba584ebd5963fefb3e7f4600f3cdda59eeda99049225f4a17fff
-  data.tar.gz: 94db4048e68964bc70e64068631a3ae01b9ef7434fab23976e69b6368f809d37
+  metadata.gz: e68467f73e8f1e909a03cd8c50f16674231dc0d070f05a5368b84e0f75dedfe6
+  data.tar.gz: 6c0b1304cb7192d223f517d5233fd96fa13aad7e0affb6832f313088bc3b3993
 SHA512:
-  metadata.gz: 144e852da54524999df466dbdf078227cae7d5e68d3155fbc3730b298072d696a39cea1c786513c34862bcb71a14b163bd202b9c203e4736598cb0fddc28813b
-  data.tar.gz: 9d76e40aa500597eec1a5a7dc02b794ccde643f603227455ccbcea76a6e074769c246335a1e554fa19bc6d06cf8cf36ad030147a651de58f148b3c4db5c12322
+  metadata.gz: 45b860d17ffc8f22cfbe4fca26d38e727ff87ddc93a959c6285fd1aaa8eb0de9c5e2a9c516f717f0f6d463b0bfe5c8708b9efa5bab5aa6b08eb642d90ee84d10
+  data.tar.gz: fe573b4b85e50373bd832f1ec3d4fdd9c11fe57bf42527fe80021d6c84d2271e01161b08cdedcee587a69bd43a28219562d36ed0c127197e4cbfe34e05902aca

data/lib/jsapi/controller/{error_result.rb → error.rb}

@@ -3,7 +3,7 @@
 module Jsapi
   module Controller
     # Used by Methods#api_operation! to produce an error response.
-    class ErrorResult
+    class Error
       delegate_missing_to :@exception
 
       # The HTTP status code of the error response to be produced.

data/lib/jsapi/controller/methods.rb

@@ -27,14 +27,18 @@ module Jsapi
       # 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.
       #
-      # The +:omit+ option specifies on which conditions properties are omitted.
+      # The +:omit+ option specifies on which conditions properties are omitted in responses.
       # 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)
+      # Raises an +ArgumentError+ when +:omit+ is other than +:empty+, +:nil+ or +nil+.
+      def api_operation(operation_name = nil,
+                        omit: nil,
+                        status: nil,
+                        strong: false,
+                        &block)
         _api_operation(
           operation_name,
           bang: false,
@@ -52,7 +56,11 @@ module Jsapi
       #     # ...
       #   end
       #
-      def api_operation!(operation_name = nil, omit: nil, status: nil, strong: false, &block)
+      def api_operation!(operation_name = nil,
+                         omit: nil,
+                         status: nil,
+                         strong: false,
+                         &block)
         _api_operation(
           operation_name,
           bang: true,
@@ -97,13 +105,13 @@ module Jsapi
       # - +: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.
+      # Raises an +ArgumentError+ when +:omit+ is other than +:empty+, +:nil+ or +nil+.
       def api_response(result, operation_name = nil, omit: nil, status: nil)
         definitions = api_definitions
         operation = _find_api_operation(operation_name, definitions)
-        response = _api_response(operation, status, definitions)
+        response_model = _api_response(operation, status, definitions)
 
-        Response.new(result, response, api_definitions, omit: omit)
+        Response.new(result, response_model, api_definitions, omit: omit)
       end
 
       private
@@ -111,40 +119,43 @@ module Jsapi
       def _api_operation(operation_name, bang:, omit:, status:, strong:, &block)
         definitions = api_definitions
         operation = _find_api_operation(operation_name, definitions)
-        response = _api_response(operation, status, definitions)
-
-        if block
-          params = _api_params(operation, definitions, strong: strong)
-          result = begin
-            raise ParametersInvalid.new(params) if bang && params.invalid?
-
-            block.call(params)
-          rescue StandardError => e
-            # Lookup a rescue handler
-            rescue_handler = definitions.rescue_handler_for(e)
-            raise e if rescue_handler.nil?
-
-            # Change the HTTP status code and response schema
-            status = rescue_handler.status
-            response = operation.response(status)&.resolve(definitions)
-            raise e if response.nil?
-
-            # Call on_rescue callbacks
-            definitions.on_rescue_callbacks.each do |callback|
-              if callback.respond_to?(:call)
-                callback.call(e)
-              else
-                send(callback, e)
-              end
-            end
 
-            ErrorResult.new(e, status: status)
+        # Perform operation
+        response_model = _api_response(operation, status, definitions)
+        head(status) && return unless block
+
+        params = _api_params(operation, definitions, strong: strong)
+
+        result = begin
+          raise ParametersInvalid.new(params) if bang && params.invalid?
+
+          block.call(params)
+        rescue StandardError => e
+          # Lookup a rescue handler
+          rescue_handler = definitions.rescue_handler_for(e)
+          raise e if rescue_handler.nil?
+
+          # Change the HTTP status code and response model
+          status = rescue_handler.status
+          response_model = operation.response(status)&.resolve(definitions)
+          raise e if response_model.nil?
+
+          # Call on_rescue callbacks
+          definitions.on_rescue_callbacks.each do |callback|
+            if callback.respond_to?(:call)
+              callback.call(e)
+            else
+              send(callback, e)
+            end
           end
-          render(json: Response.new(result, response, definitions, omit: omit), status: status)
-        else
-          head(status)
+
+          Error.new(e, status: status)
         end
-        self.content_type = response.content_type
+        response = Response.new(result, response_model, definitions, omit: omit)
+
+        # Write response
+        self.content_type = response_model.content_type
+        render(json: response, status: status)
       end
 
       def _api_params(operation, definitions, strong:)

data/lib/jsapi/controller/parameters.rb

@@ -27,7 +27,8 @@ module Jsapi
           @raw_attributes[name] = JSON.wrap(
             parameter_model.in == 'header' ? headers[name] : @params[name],
             parameter_model.schema.resolve(definitions),
-            definitions
+            definitions,
+            context: :request
           )
         end
 
@@ -38,7 +39,8 @@ module Jsapi
           request_body = JSON.wrap(
             @params.except(*operation.parameters.keys),
             request_body_schema,
-            definitions
+            definitions,
+            context: :request
           )
           @raw_attributes.merge!(request_body.raw_attributes)
           @raw_additional_attributes = request_body.raw_additional_attributes

data/lib/jsapi/controller/response.rb

@@ -2,10 +2,20 @@
 
 module Jsapi
   module Controller
-    # Used to serialize a response.
+    # Used to jsonify a response.
     class Response
+      class JsonifyError < RuntimeError # :nodoc:
+        def message
+          [@path&.delete_prefix('.') || 'response body', super].join(' ')
+        end
+
+        def prepend(origin)
+          @path = "#{origin}#{@path}"
+          self
+        end
+      end
 
-      # Creates a new instance to serialize +object+ according to +response+. References
+      # Creates a new instance to jsonify +object+ according to +response+. References
       # are resolved to API components in +definitions+.
       #
       # The +:omit+ option specifies on which conditions properties are omitted.
@@ -14,111 +24,119 @@ module Jsapi
       # - +: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.
+      # Raises an +ArgumentError+ when +:omit+ is other than +:empty+, +:nil+ or +nil+.
       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
+
+        @omittable_check =
+          case omit
+          when nil
+            nil
+          when :nil
+            ->(value, schema) { schema.omittable? && value.nil? }
+          when :empty
+            ->(value, schema) { schema.omittable? && value.try(:empty?) }
+          else
+            raise InvalidArgumentError.new('omit', omit, valid_values: %i[empty nil])
+          end
       end
 
       def inspect # :nodoc:
         "#<#{self.class.name} #{@object.inspect}>"
       end
 
-      # Returns the JSON representation of the response as a +String+.
+      # Returns the \JSON representation of the response as a string.
       def to_json(*)
         schema = @response.schema.resolve(@definitions)
         if @response.locale
-          I18n.with_locale(@response.locale) do
-            serialize(@object, schema)
-          end
+          I18n.with_locale(@response.locale) { jsonify(@object, schema) }
         else
-          serialize(@object, schema)
+          jsonify(@object, schema)
         end.to_json
       end
 
       private
 
-      def serialize(object, schema, path = nil)
+      def jsonify(object, schema)
         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
-        when 'array'
-          serialize_array(object, schema, path)
-        when 'integer'
-          schema.convert(object.to_i)
-        when 'number'
-          schema.convert(object.to_f)
-        when 'object'
-          serialize_object(object, schema, path)
-        when 'string'
-          schema.convert(
-            case schema.format
-            when 'date'
-              object.to_date
-            when 'date-time'
-              object.to_datetime
-            when 'duration'
-              object.iso8601
-            else
-              object.to_s
-            end
-          )
+
+        if object.nil?
+          raise JsonifyError, "can't be nil" unless schema.nullable?
         else
-          object
+          case schema.type
+          when 'array'
+            jsonify_array(object, schema)
+          when 'boolean'
+            object
+          when 'integer'
+            schema.convert(object.to_i)
+          when 'number'
+            schema.convert(object.to_f)
+          when 'object'
+            jsonify_object(object, schema)
+          when 'string'
+            schema.convert(
+              case schema.format
+              when 'date'
+                object.to_date
+              when 'date-time'
+                object.to_datetime
+              when 'duration'
+                object.iso8601
+              else
+                object.to_s
+              end
+            )
+          else
+            raise JsonifyError, "has an invalid type: #{schema.type.inspect}"
+          end
         end
       end
 
-      def serialize_array(array, schema, path)
+      def jsonify_array(array, schema)
         item_schema = schema.items.resolve(@definitions)
-        Array(array).map { |item| serialize(item, item_schema, path) }
+        index = 0
+
+        Array(array).map do |item|
+          item = jsonify(item, item_schema)
+          index += 1
+          item
+        rescue JsonifyError => e
+          raise e.prepend("[#{index}]")
+        end
       end
 
-      def serialize_object(object, schema, path)
+      def jsonify_object(object, schema)
         schema = schema.resolve_schema(object, @definitions, context: :response)
         properties = {}
 
-        # Serialize properties
-        schema.resolve_properties(@definitions, context: :response).each do |key, property|
+        # Add properties
+        schema.resolve_properties(@definitions, context: :response).each_value do |property|
           property_schema = property.schema.resolve(@definitions)
           property_value = property.reader.call(object)
           property_value = property_schema.default if property_value.nil?
+          next if @omittable_check&.call(property_value, property_schema)
 
-          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}"
-          )
+          properties[property.name] = jsonify(property_value, property_schema)
+        rescue JsonifyError => e
+          raise e.prepend(".#{property.name}")
         end
-        # Serialize additional properties
+        # Add 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)
 
-            properties[key] = serialize(
-              value,
-              additional_properties_schema,
-              path.nil? ? key : "#{path}.#{key}"
-            )
+            properties[key] = jsonify(value, additional_properties_schema)
+          rescue JsonifyError => e
+            raise e.prepend(".#{key}")
           end
         end
-        # Return properties if present, otherwise nil
-        properties if properties.present?
+
+        properties.presence
       end
     end
   end

data/lib/jsapi/controller.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'controller/parameters_invalid'
-require_relative 'controller/error_result'
+require_relative 'controller/error'
 require_relative 'controller/parameters'
 require_relative 'controller/response'
 require_relative 'controller/methods'

data/lib/jsapi/dsl/base.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module DSL
+    class Base
+      def initialize(meta_model, &block)
+        @meta_model = meta_model
+
+        if block
+          if meta_model.reference?
+            raise Error, "reference can't be specified together with a block"
+          end
+
+          instance_eval(&block)
+        end
+      end
+
+      def respond_to_missing?(*args) # :nodoc:
+        keyword?(args.first)
+      end
+
+      private
+
+      def define(*args, &block)
+        block.call
+      rescue Error => e
+        raise e.prepend_origin(args.compact.join(' '))
+      rescue StandardError => e
+        raise Error.new(e, args.compact.join(' ').presence)
+      end
+
+      def find_method(name)
+        ["#{name}=", "add_#{name}"].find do |method|
+          @meta_model.respond_to?(method)
+        end
+      end
+
+      def keyword(name, *params, &block)
+        method = find_method(name)
+        raise "unsupported keyword: #{name}" unless method
+
+        define(name) do
+          result = @meta_model.public_send(method, *params)
+          Base.new(result, &block) if block
+        end
+      end
+
+      def keyword?(name)
+        find_method(name).present?
+      end
+
+      alias method_missing keyword
+    end
+  end
+end

data/lib/jsapi/dsl/callback.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module DSL
+    # Used to specify an OpenAPI callback object.
+    class Callback < Base
+
+      # Adds a callback operation.
+      #
+      #   operation '{$request.query.foo}' do
+      #     parameter 'bar', type: 'string'
+      #   end
+      def operation(expression, **keywords, &block)
+        define('operation', expression.inspect) do
+          operation_model = @meta_model.add_operation(expression, keywords)
+          Operation.new(operation_model, &block) if block
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/dsl/class_methods.rb

@@ -3,9 +3,27 @@
 module Jsapi
   module DSL
     module ClassMethods
+      # Specifies the base path of the API.
+      #
+      #   api_base_path '/foo'
+      #
+      def api_base_path(arg)
+        api_definitions { base_path(arg) }
+      end
+
+      # Specifies a reusable callback.
+      #
+      #   api_callback 'onFoo' do
+      #     operation '{$request.query.foo}', path: '/bar'
+      #   end
+      #
+      def api_callback(name, **keywords, &block)
+        api_definitions { callback(name, **keywords, &block) }
+      end
+
       # Specifies the general default values for +type+.
       #
-      #   api_default 'array', read: [], write: []
+      #   api_default 'array', within_requests: [], within_responses: []
       #
       def api_default(type, **keywords, &block)
         api_definitions { default(type, **keywords, &block) }
@@ -21,17 +39,72 @@ module Jsapi
         @api_definitions
       end
 
+      # Specifies a reusable example.
+      #
+      #   example 'foo', value: 'bar'
+      #
+      def api_example(name, **keywords, &block)
+        api_definitions { example(name, **keywords, &block) }
+      end
+
+      # Specifies the external documentation.
+      #
+      #   api_external_docs url: 'https://foo.bar'
+      #
+      def api_external_docs(**keywords, &block)
+        api_definitions { external_docs(**keywords, &block) }
+      end
+
+      # Specifies a reusable header.
+      #
+      #   api_header 'foo', type: 'string'
+      #
+      def api_header(name, **keywords, &block)
+        api_definitions { header(name, **keywords, &block) }
+      end
+
+      # Specifies the host serving the API.
+      #
+      #   api_host 'foo.bar'
+      #
+      def api_host(arg)
+        api_definitions { host(arg) }
+      end
+
       # Includes API definitions from +klasses+.
       def api_include(*klasses)
         api_definitions { include(*klasses) }
       end
 
+      # Specifies general information about the API.
+      #
+      #   api_info title: 'Foo', version: '1' do
+      #     contact name: 'bar'
+      #   end
+      def api_info(**keywords, &block)
+        api_definitions { info(**keywords, &block) }
+      end
+
+      # Specifies a reusable link.
+      #
+      #   api_link 'foo', operation_id: 'bar'
+      #
+      def api_link(name, **keywords, &block)
+        api_definitions { link(name, **keywords, &block) }
+      end
+
       # Registers a callback to be called when rescuing an exception.
+      #
+      #   api_on_rescue :foo
+      #
+      #   api_on_rescue do |error|
+      #     # ...
+      #   end
       def api_on_rescue(method = nil, &block)
         api_definitions { on_rescue(method, &block) }
       end
 
-      # Defines an operation.
+      # Specifies an operation.
       #
       #   api_operation 'foo', path: '/foo' do
       #     parameter 'bar', type: 'string'
@@ -45,7 +118,7 @@ module Jsapi
         api_definitions { operation(name, **keywords, &block) }
       end
 
-      # Defines a reusable parameter.
+      # Specifies a reusable parameter.
       #
       #   api_parameter 'foo', type: 'string'
       #
@@ -70,7 +143,7 @@ module Jsapi
         api_definitions { rescue_from(*klasses, with: with) }
       end
 
-      # Defines a reusable response.
+      # Specifies a reusable response.
       #
       #   api_response 'Foo', type: 'object' do
       #     property 'bar', type: 'string'
@@ -79,7 +152,7 @@ module Jsapi
         api_definitions { response(name, **keywords, &block) }
       end
 
-      # Defines a reusable schema.
+      # Specifies a reusable schema.
       #
       #   api_schema 'Foo' do
       #     property 'bar', type: 'string'
@@ -88,13 +161,46 @@ module Jsapi
         api_definitions { schema(name, **keywords, &block) }
       end
 
-      # Defines the root of an OpenAPI document.
+      # Specifies a URI scheme supported by the API.
+      #
+      #   api_scheme 'https'
+      #
+      def api_scheme(arg)
+        api_definitions { scheme(arg) }
+      end
+
+      # Specifies a security requirement.
       #
-      #   openapi do
-      #     info title: 'Foo', version: '1'
+      #   api_security_requirement do
+      #     scheme 'basic_auth'
       #   end
-      def openapi(**keywords, &block)
-        api_definitions { openapi(**keywords, &block) }
+      #
+      def api_security_requirement(**keywords, &block)
+        api_definitions { security_requirement(**keywords, &block) }
+      end
+
+      # Specifies a security scheme.
+      #
+      #   api_security_scheme 'basic_auth', type: 'http', scheme: 'basic'
+      #
+      def api_security_scheme(name, **keywords, &block)
+        api_definitions { security_scheme(name, **keywords, &block) }
+      end
+
+      # Specifies a server providing the API.
+      #
+      #   api_server url: 'https://foo.bar/foo'
+      #
+      def api_server(**keywords, &block)
+        api_definitions { server(**keywords, &block) }
+      end
+
+      # Specifies a tag.
+      #
+      #   api_tag name: 'foo', description: 'description of foo'
+      #
+      def api_tag(**keywords, &block)
+        api_definitions { tag(**keywords, &block) }
       end
     end
   end