jsapi 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4326454795353f4fc3d2513d4b58b5d42df113665fb3e7b197e2aac0917de794
+  data.tar.gz: 3f25ce60031f26bb76b3a4dbebd7cf9cd333ae928bc59d12aee46d215206dcc2
+SHA512:
+  metadata.gz: 1f0304f56a303c1e2658ddaf31a40c0e3d6ad4584094896cc6eeb9fb40c919e91f45fffa9bc47a0f8096426eadcd301987de313f5145b779974d874f89988a4e
+  data.tar.gz: b2255d64dc7c9e8b05c639a2e62fbc7e33dc71074d3284aedd5788de4da8951c9aebc00c8589a4240bcf450f17ba8090696e96ea5a1259e3c81004fc3b2e9776

data/lib/jsapi/controller/base.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Controller
+    # The base API controller class.
+    #
+    #   class FooController < Jsapi::Controller::Base
+    #     api_operation do
+    #       response type: 'string'
+    #     end
+    #
+    #     def index
+    #       api_operation { 'Hello world' }
+    #     end
+    #   end
+    class Base < ActionController::API
+      include DSL
+      include Methods
+    end
+  end
+end

data/lib/jsapi/controller/error_result.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Controller
+    # Used by +api_operation!+ to produce an error response.
+    class ErrorResult
+
+      # 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:)
+        @exception = exception
+        @status = status
+      end
+    end
+  end
+end

data/lib/jsapi/controller/methods.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Controller
+    module Methods
+      # Returns the Meta::Definitions instance associated with the controller class.
+      # This method can be used to create an OpenAPI document, for example:
+      #
+      #   render(json: api_definitions.openapi_document)
+      #
+      def api_definitions
+        self.class.api_definitions
+      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. The
+      # object returned by the block is implicitly rendered according to the
+      # appropriate +response+ specification.
+      #
+      #   api_operation('foo') do |api_params|
+      #     # ...
+      #   end
+      #
+      # +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 that the model passed to the block is invalid if there are any
+      # request parameters that cannot be mapped to a parameter or a request body
+      # property of the operation.
+      #
+      def api_operation(operation_name = nil, status: nil, strong: false, &block)
+        _perform_api_operation(
+          operation_name, false,
+          status: status,
+          strong: strong,
+          &block
+        )
+      end
+
+      # Like +api_operation+, except that a ParametersInvalid exception is raised
+      # if the request parameters are invalid.
+      #
+      #   api_operation!('foo') do |api_params|
+      #     # ...
+      #   end
+      #
+      def api_operation!(operation_name = nil, status: nil, strong: false, &block)
+        _perform_api_operation(
+          operation_name, true,
+          status: status,
+          strong: strong,
+          &block
+        )
+      end
+
+      # Returns the request parameters as an instance of the operation's model class.
+      #
+      #   params = api_params('foo')
+      #
+      # +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 that the model returned is invalid if there are any request
+      # parameters that cannot be mapped to a parameter or a request body property
+      # of the operation.
+      #
+      # Note that each call of +api_params+ returns a newly created instance.
+      #
+      def api_params(operation_name = nil, strong: false)
+        definitions = api_definitions
+        _api_params(
+          _api_operation(operation_name, definitions),
+          definitions,
+          strong: strong
+        )
+      end
+
+      # Returns a Response to serialize the JSON representation of +result+ according
+      # to the appropriate +response+ specification.
+      #
+      #   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)
+        definitions = api_definitions
+        operation = _api_operation(operation_name, definitions)
+        response = _api_response(operation, status, definitions)
+
+        Response.new(result, response, api_definitions)
+      end
+
+      private
+
+      def _api_operation(operation_name, definitions)
+        operation = definitions.operation(operation_name)
+        return operation if operation
+
+        raise "operation not defined: #{operation_name}"
+      end
+
+      def _api_params(operation, definitions, strong:)
+        (operation.model || Model::Base).new(
+          Parameters.new(params, operation, definitions, strong: strong)
+        )
+      end
+
+      def _api_response(operation, status, definitions)
+        response = operation.response(status)
+        return response.resolve(definitions) if response
+
+        raise "status code not defined: #{status}"
+      end
+
+      def _perform_api_operation(operation_name, bang, status:, strong:, &block)
+        definitions = api_definitions
+        operation = _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?
+
+            ErrorResult.new(e, status: status)
+          end
+          render(json: Response.new(result, response, definitions), status: status)
+        else
+          head(status)
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/controller/parameters.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Controller
+    # Used to wrap request parameters.
+    class Parameters
+      include Model::Nestable
+
+      attr_reader :raw_attributes
+
+      # Creates a new instance that wraps +params+ according to +operation+.
+      # References are resolved to API components in +definitions+.
+      #
+      # 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 cannot be mapped to a parameter or a request body
+      # property of +operation+.
+      def initialize(params, operation, definitions, strong: false)
+        @params = params
+        @strong = strong == true
+        @raw_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
+
+        # Wrap params
+        meta_models.each do |name, meta_model|
+          @raw_attributes[name] =
+            JSON.wrap(params[name], meta_model.schema, definitions)
+        end
+      end
+
+      def inspect # :nodoc:
+        "#<#{self.class.name} " \
+        "#{attributes.map { |k, v| "#{k}: #{v.inspect}" }.join(', ')}>"
+      end
+
+      # Validates the request parameters. Returns true if the parameters are
+      # valid, false otherwise. Detected errors are added to +errors+.
+      def validate(errors)
+        [
+          validate_attributes(errors),
+          !@strong || validate_parameters(
+            @params.except(:controller, :action),
+            attributes,
+            errors
+          )
+        ].all?
+      end
+
+      private
+
+      def validate_parameters(params, attributes, errors, path = [])
+        params.each.map do |key, value|
+          if attributes.key?(key)
+            # Validate nested parameters
+            !value.respond_to?(:keys) || validate_parameters(
+              value,
+              attributes[key].try(:attributes) || {},
+              errors,
+              path + [key]
+            )
+          else
+            errors.add(
+              :base,
+              I18n.translate(
+                'jsapi.errors.forbidden',
+                default: "'%<name>s' isn't allowed",
+                name: path.empty? ? key : (path + [key]).join('.')
+              )
+            )
+            false
+          end
+        end.all?
+      end
+    end
+  end
+end

data/lib/jsapi/controller/parameters_invalid.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Controller
+    # Raised by Methods#api_operation! if the request parameters are invalid.
+    class ParametersInvalid < StandardError
+      attr_reader :params
+
+      def initialize(params)
+        @params = params
+        super('')
+      end
+
+      # Overrides <code>StandardError#message</code> to lazily generate the
+      # error message.
+      def message
+        "#{
+          @params.errors.full_messages.map do |message|
+            message.delete_suffix('.')
+          end.join('. ')
+        }."
+      end
+    end
+  end
+end

data/lib/jsapi/controller/response.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Controller
+    # Used to serialize a response.
+    class Response
+
+      # Creates a new instance to serialize +object+ according to +response+.
+      # References are resolved to API components in +definitions+.
+      def initialize(object, response, definitions)
+        @object = object
+        @response = response
+        @definitions = definitions
+      end
+
+      def inspect # :nodoc:
+        "#<#{self.class.name} #{@object.inspect}>"
+      end
+
+      # 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
+        else
+          serialize(@object, schema)
+        end.to_json
+      end
+
+      private
+
+      def serialize(object, schema, path = nil)
+        return if object.nil? && schema.nullable?
+        raise "#{path || 'response'} can't be nil" if object.nil?
+
+        case schema.type
+        when 'array'
+          item_schema = schema.items.resolve(@definitions)
+          Array(object).map { |item| serialize(item, item_schema, path) }
+        when 'integer'
+          schema.convert(object.to_i)
+        when 'number'
+          schema.convert(object.to_f)
+        when 'object'
+          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
+              ),
+              @definitions
+            )
+          end
+          # Serialize properties
+          schema.resolve_properties(:read, @definitions).transform_values do |property|
+            serialize(
+              object.public_send(property.source || property.name),
+              property.schema.resolve(@definitions),
+              path.nil? ? property.name : "#{path}.#{property.name}"
+            )
+          end
+        when 'string'
+          schema.convert(
+            case schema.format
+            when 'date'
+              object.to_date
+            when 'date-time'
+              object.to_datetime
+            else
+              object.to_s
+            end
+          )
+        else
+          object
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/controller.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'controller/parameters_invalid'
+require_relative 'controller/error_result'
+require_relative 'controller/parameters'
+require_relative 'controller/response'
+require_relative 'controller/methods'
+require_relative 'controller/base'
+
+module Jsapi
+  # Provides classes and modules to implement API controllers.
+  module Controller end
+end

data/lib/jsapi/dsl/callbacks.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module DSL
+    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

data/lib/jsapi/dsl/class_methods.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module DSL
+    module ClassMethods
+      # The API definitions of the current class.
+      def api_definitions(&block)
+        @api_definitions ||= Meta::Definitions.new(self)
+        Definitions.new(@api_definitions, &block) if block
+        @api_definitions
+      end
+
+      # Includes API definitions from +klasses+.
+      def api_include(*klasses)
+        api_definitions { include(*klasses) }
+      end
+
+      # Defines an operation.
+      #
+      #   api_operation 'foo', path: '/foo' do
+      #     parameter 'bar', type: 'string'
+      #     response do
+      #       property 'foo', type: 'string'
+      #     end
+      #   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) }
+      end
+
+      # Defines a reusable parameter.
+      #
+      #   api_parameter 'foo', type: 'string'
+      #
+      def api_parameter(name, **options, &block)
+        api_definitions { parameter(name, **options, &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) }
+      end
+
+      # Specifies the HTTP status code of an error response rendered when an
+      # exception of any of +klasses+ has been raised.
+      #
+      #   api_rescue_from Jsapi::Controller::ParametersInvalid, with: 400
+      #
+      def api_rescue_from(*klasses, with: nil)
+        api_definitions { rescue_from(*klasses, with: with) }
+      end
+
+      # Defines a reusable response.
+      #
+      #   api_response 'Foo', type: 'object' do
+      #     property 'bar', type: 'string'
+      #   end
+      def api_response(name, **options, &block)
+        api_definitions { response(name, **options, &block) }
+      end
+
+      # Defines a reusable schema.
+      #
+      #   api_schema 'Foo' do
+      #     property 'bar', type: 'string'
+      #   end
+      def api_schema(name, **options, &block)
+        api_definitions { schema(name, **options, &block) }
+      end
+
+      # Defines the root of an OpenAPI document.
+      #
+      #   openapi do
+      #     info title: 'Foo', version: '1'
+      #   end
+      def openapi(**keywords, &block)
+        api_definitions { openapi(**keywords, &block) }
+      end
+    end
+  end
+end

data/lib/jsapi/dsl/definitions.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module DSL
+    # Used to define top-level API components.
+    class Definitions < Node
+
+      # Includes API definitions from +klasses+.
+      def include(*klasses)
+        klasses.each do |klass|
+          _meta_model.include(klass.api_definitions)
+        end
+      end
+
+      # Defines the root of an OpenAPI document.
+      #
+      #   openapi do
+      #     info title: 'Foo', version: '1'
+      #   end
+      def openapi(**keywords, &block)
+        _define('openapi') do
+          _meta_model.openapi_root = keywords
+          OpenAPI::Root.new(_meta_model.openapi_root, &block) if block
+        end
+      end
+
+      # Defines an operation.
+      #
+      #   operation 'foo', path: '/foo' do
+      #     parameter 'bar', type: 'string'
+      #     response do
+      #       property 'foo', type: 'string'
+      #     end
+      #   end
+      #
+      # +name+ can be +nil+ if the controller handles one operation only.
+      def operation(name = nil, **keywords, &block)
+        _define('operation', name&.inspect) do
+          operation_model = _meta_model.add_operation(name, keywords)
+          Operation.new(operation_model, &block) if block
+        end
+      end
+
+      # Defines a reusable parameter.
+      #
+      #   parameter 'foo', type: 'string'
+      #
+      def parameter(name, **keywords, &block)
+        _define('parameter', name.inspect) do
+          parameter_model = _meta_model.add_parameter(name, keywords)
+          Parameter.new(parameter_model, &block) if block
+        end
+      end
+
+      # Defines a reusable request body.
+      #
+      #   request_body 'foo', type: 'string'
+      #
+      def request_body(name, **keywords, &block)
+        _define('request_body', name.inspect) do
+          request_body_model = _meta_model.add_request_body(name, keywords)
+          RequestBody.new(request_body_model, &block) if block
+        end
+      end
+
+      # Specifies the HTTP status code of an error response rendered when an
+      # exception of any of +klasses+ has been raised.
+      #
+      #   rescue_from Jsapi::Controller::ParametersInvalid, with: 400
+      #
+      def rescue_from(*klasses, with: nil)
+        klasses.each do |klass|
+          _meta_model.add_rescue_handler(klass, status: with)
+        end
+      end
+
+      # Defines a reusable response.
+      #
+      #   response 'Foo', type: 'object' do
+      #     property 'bar', type: 'string'
+      #   end
+      def response(name, **keywords, &block)
+        _define('response', name.inspect) do
+          response_model = _meta_model.add_response(name, keywords)
+          Response.new(response_model, &block) if block
+        end
+      end
+
+      # Defines a reusable schema.
+      #
+      #   schema 'Foo' do
+      #     property 'bar', type: 'string'
+      #   end
+      def schema(name, **keywords, &block)
+        _define('schema', name.inspect) do
+          schema_model = _meta_model.add_schema(name, keywords)
+          Schema.new(schema_model, &block) if block
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/dsl/error.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module DSL
+    # Raised when an error occurred while defining an API component.
+    class Error < StandardError
+
+      # Creates a new error. +origin+ is the innermost position at where
+      # the error occurred.
+      def initialize(error_or_message, origin = nil)
+        @path = Array(origin)
+        super(
+          if error_or_message.respond_to?(:message)
+            error_or_message.message
+          else
+            error_or_message
+          end
+        )
+      end
+
+      # Overrides <code>StandardError#message</code> to append the whole path of
+      # the position at where the error occurred, for example:
+      # <code>{message} (at foo / bar)</code>.
+      def message
+        message = super
+        return message if @path.empty?
+
+        "#{message} (at #{@path.join(' / ')})"
+      end
+
+      # Prepends +origin+ to the path at where the error occurred.
+      def prepend_origin(origin)
+        @path.prepend(origin) if origin.present?
+        self
+      end
+    end
+  end
+end

data/lib/jsapi/dsl/examples.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module DSL
+    module Examples
+      # Defines 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