jsapi 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72aa6ad77a99ade6acb3d5c70b6521b640e012cccc7e9ab00b9d55db3062d4d6
-  data.tar.gz: 96ec077740dde1963ca6b448662e1f4370f3bc0b54778db2d03d9447ba69aa3b
+  metadata.gz: 5740302f08b361b1f70f50844a1c3858e8bf2d29b781ea245ec201c2290fb3f4
+  data.tar.gz: 27f401b21f5fece8a1dd675ab8597a7822d101a3d738a6f5ef76e5a8969dca8d
 SHA512:
-  metadata.gz: ec7997fbedc7c9035f9e36d5426b23502b87f4c4c654b1e02f93db711f514a8a434d371dc4761156165c439256ad3f339c7a151b1b35c8dcbf3d1e14f1fd4628
-  data.tar.gz: 1f2952e80bf883302fd835f9425bae0bd2e7629b2746d3abec4b19a259c5abbd9869534b18eb6c69afd94a9397e13c7d86d78720f3573d92ef355b1e66b99fb0
+  metadata.gz: fe84b39402a26fa951058ba59fab7cc20e0e0321c74826b672bd65b87a4975d68f37517bfa54f62549f2287c3221702d4d338e312ae01551481f5a529a865f40
+  data.tar.gz: 476347dfb1a27d43dc42835d87a845a75806a7a6c6f721ad9e372d53d435650c685b9cf7c8cb70f34718dffc675e1536475851b841e549b50789f9f08965aa33

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. 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. Parameter names
+      # are converted to snake case. The object returned by the block is implicitly rendered
+      # according to the appropriate +response+ specification.
       #
       #   api_operation('foo') do |api_params|
       #     # ...
@@ -53,6 +53,7 @@ module Jsapi
       end
 
       # Returns the request parameters as an instance of the operation's model class.
+      # Parameter names are converted to snake case.
       #
       #   params = api_params('foo')
       #
@@ -129,6 +130,15 @@ module Jsapi
             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)
           end
           render(json: Response.new(result, response, definitions), status: status)

data/lib/jsapi/controller/parameters.rb

@@ -25,15 +25,12 @@ module Jsapi
         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)
-          )
+          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)
+          @raw_attributes[name.underscore] = JSON.wrap(params[name], meta_model.schema, definitions)
         end
       end
 

data/lib/jsapi/controller/response.rb

@@ -5,8 +5,8 @@ module Jsapi
     # 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+.
+      # 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
@@ -37,33 +37,13 @@ module Jsapi
 
         case schema.type
         when 'array'
-          item_schema = schema.items.resolve(@definitions)
-          Array(object).map { |item| serialize(item, item_schema, path) }
+          serialize_array(object, 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
+          serialize_object(object, schema, path)
         when 'string'
           schema.convert(
             case schema.format
@@ -81,6 +61,48 @@ module Jsapi
           object
         end
       end
+
+      def serialize_array(array, schema, path)
+        item_schema = schema.items.resolve(@definitions)
+        Array(array).map { |item| serialize(item, item_schema, path) }
+      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
+        # 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),
+            path.nil? ? property.name : "#{path}.#{property.name}"
+          )
+        end
+        if (additional_properties = schema.additional_properties&.resolve(@definitions))
+          additional_properties_schema = additional_properties.schema.resolve(@definitions)
+
+          object.public_send(additional_properties.source)&.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,
+              path.nil? ? key : "#{path}.#{key}"
+            )
+          end
+        end
+        properties
+      end
     end
   end
 end

data/lib/jsapi/dsl/class_methods.rb

@@ -15,6 +15,11 @@ module Jsapi
         api_definitions { include(*klasses) }
       end
 
+      # Registers a callback to be called when rescuing an exception.
+      def api_on_rescue(method = nil, &block)
+        api_definitions { on_rescue(method, &block) }
+      end
+
       # Defines an operation.
       #
       #   api_operation 'foo', path: '/foo' do

data/lib/jsapi/dsl/definitions.rb

@@ -12,6 +12,13 @@ module Jsapi
         end
       end
 
+      # Registers a callback to be called when rescuing an exception.
+      def on_rescue(method = nil, &block)
+        _define('on_rescue') do
+          _meta_model.add_on_rescue(method || block)
+        end
+      end
+
       # Defines the root of an \OpenAPI document.
       #
       #   openapi do

data/lib/jsapi/json/object.rb

@@ -11,16 +11,13 @@ module Jsapi
       def initialize(attributes, schema, definitions)
         # Select inherriting schema on polymorphism
         if (discriminator = schema.discriminator)
-          schema = discriminator.resolve(
-            attributes[discriminator.property_name],
-            definitions
-          )
+          schema = discriminator.resolve(attributes[discriminator.property_name], 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_attributes =
+          schema.resolve_properties(:write, definitions).transform_values do |property|
+            JSON.wrap(attributes[property.name], property.schema, definitions)
+          end
 
         super(schema)
       end

data/lib/jsapi/meta/definitions.rb

@@ -3,10 +3,11 @@
 module Jsapi
   module Meta
     class Definitions
-      attr_reader :examples, :openapi_root, :operations, :parameters,
+      attr_reader :callbacks, :examples, :openapi_root, :operations, :parameters,
                   :request_bodies, :rescue_handlers, :responses, :schemas
 
       def initialize(owner = nil)
+        @callbacks = { on_rescue: [] }
         @owner = owner
         @examples = {}
         @operations = {}
@@ -19,7 +20,11 @@ module Jsapi
       end
 
       def add_example(name, keywords = {})
-        @examples[name.to_s] = Example.new(keywords)
+        @examples[name.to_s] = OpenAPI::Example.new(keywords)
+      end
+
+      def add_on_rescue(method_or_proc)
+        @callbacks[:on_rescue] << method_or_proc
       end
 
       def add_operation(name = nil, keywords = {})
@@ -86,6 +91,12 @@ module Jsapi
         end
       end
 
+      def on_rescue_callbacks
+        @self_and_included.flat_map do |definitions|
+          definitions.callbacks[:on_rescue]
+        end
+      end
+
       # Returns a hash representing the OpenAPI document for +version+.
       # Raises an +ArgumentError+ if +version+ is not supported.
       def openapi_document(version = nil)
@@ -101,15 +112,13 @@ module Jsapi
               responses: openapi_responses(version)
             )
           else
-            h.deep_merge!(
-              components: {
-                schemas: openapi_schemas(version),
-                parameters: openapi_parameters(version),
-                requestBodies: openapi_request_bodies(version),
-                responses: openapi_responses(version),
-                examples: openapi_examples
-              }.compact.presence
-            )
+            h[:components] = (h[:components] || {}).merge(
+              schemas: openapi_schemas(version),
+              parameters: openapi_parameters(version),
+              requestBodies: openapi_request_bodies(version),
+              responses: openapi_responses(version),
+              examples: openapi_examples
+            ).compact.presence
           end
         end.compact
       end

data/lib/jsapi/meta/openapi/callback/model.rb

@@ -23,7 +23,7 @@ module Jsapi
             @operations&.[](expression&.to_s)
           end
 
-          # Returns a hash representing the callback object.
+          # Returns a hash representing the \OpenAPI callback object.
           def to_openapi(version, definitions)
             operations.transform_values do |operation|
               { operation.method => operation.to_openapi(version, definitions) }

data/lib/jsapi/meta/openapi/contact.rb

@@ -5,6 +5,8 @@ module Jsapi
     module OpenAPI
       # Represents a contact object.
       class Contact < Base
+        include Extensions
+
         ##
         # :attr: email
         # The email address of the contact.
@@ -20,13 +22,9 @@ module Jsapi
         # The URL of the contact.
         attribute :url, String
 
-        # Returns a hash representing the contact object.
+        # Returns a hash representing the \OpenAPI contact object.
         def to_openapi(*)
-          {
-            name: name,
-            url: url,
-            email: email
-          }.compact
+          with_openapi_extensions(name: name, url: url, email: email)
         end
       end
     end

data/lib/jsapi/meta/openapi/example/model.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module Example
+        class Model < Base
+          include Extensions
+
+          ##
+          # :attr: description
+          # The optional description of the example.
+          attribute :description, String
+
+          ##
+          # :attr: external
+          # If true, +value+ is interpreted as a URI pointing to an external sample value.
+          attribute :external, values: [true, false]
+
+          ##
+          # :attr: summary
+          # The optional summary of the example.
+          attribute :summary, String
+
+          ##
+          # :attr: value
+          # The sample value.
+          attribute :value
+
+          # Returns a hash representing the \OpenAPI example object.
+          def to_openapi(*)
+            with_openapi_extensions(summary: summary, description: description).tap do |hash|
+              if external?
+                hash[:external_value] = value
+              else
+                hash[:value] = value
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/openapi/example/reference.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module Example
+        class Reference < BaseReference
+          # Returns a hash representing the \OpenAPI reference object.
+          def to_openapi(*)
+            { '$ref': "#/components/examples/#{ref}" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/openapi/example.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'example/model'
+require_relative 'example/reference'
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module Example
+        class << self
+          # Creates a new example model or reference.
+          def new(keywords = {})
+            return Reference.new(keywords) if keywords.key?(:ref)
+
+            Model.new(keywords)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/openapi/extensions.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module Extensions
+        # Adds an \OpenAPI extension.
+        #
+        # Raises an +ArgumentError+ if +name+ is blank.
+        def add_openapi_extension(name, value = nil)
+          raise ArgumentError, "name can't be blank" if name.blank?
+
+          openapi_extensions["x-#{name}".to_sym] = value
+        end
+
+        # Returns a hash containing the \OpenAPI extensions.
+        def openapi_extensions
+          @openapi_extensions ||= {}
+        end
+
+        private
+
+        def with_openapi_extensions(keywords = {}) # :nodoc:
+          keywords.merge!(openapi_extensions)
+          keywords.compact!
+          keywords
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/openapi/external_documentation.rb

@@ -5,6 +5,8 @@ module Jsapi
     module OpenAPI
       # Represents an external documentation object.
       class ExternalDocumentation < Base
+        include Extensions
+
         ##
         # :attr: description
         # The optional description of the external documentation.
@@ -15,12 +17,9 @@ module Jsapi
         # The URL of the external documentation.
         attribute :url, String
 
-        # Returns a hash representing the external documentation object.
+        # Returns a hash representing the \OpenAPI external documentation object.
         def to_openapi(*)
-          {
-            url: url,
-            description: description
-          }.compact
+          with_openapi_extensions(url: url, description: description)
         end
       end
     end

data/lib/jsapi/meta/openapi/header/model.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module Header
+        class Model < Base
+          include Extensions
+
+          ##
+          # :attr: deprecated
+          # Specifies whether or not the header is deprecated.
+          attribute :deprecated, values: [true, false]
+
+          ##
+          # :attr: description
+          # The description of the header.
+          attribute :description, String
+
+          ##
+          # :attr_reader: examples
+          # One or more example values.
+          attribute :examples, { String => Example }, default_key: 'default'
+
+          ##
+          # :attr_reader: schema
+          # The Schema of the header.
+          attribute :schema, writer: false
+
+          delegate_missing_to :schema
+
+          def initialize(keywords = {})
+            keywords = keywords.dup
+            super(keywords.extract!(:deprecated, :description, :examples))
+
+            add_example(value: keywords.delete(:example)) if keywords.key?(:example)
+
+            @schema = Schema.new(keywords)
+          end
+
+          # Returns a hash representing the \OpenAPI header object.
+          def to_openapi(version)
+            version = OpenAPI::Version.from(version)
+
+            with_openapi_extensions(
+              if version.major == 2
+                schema.to_openapi(version).merge(
+                  description: description
+                )
+              else
+                {
+                  description: description,
+                  deprecated: deprecated?.presence,
+                  schema: schema.to_openapi(version),
+                  examples: examples&.transform_values(&:to_openapi)
+                }
+              end
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/openapi/header/reference.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module Header
+        class Reference < BaseReference
+          # Returns a hash representing the \OpenAPI reference object.
+          def to_openapi(*)
+            { '$ref': "#/components/headers/#{ref}" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/openapi/header.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'header/model'
+require_relative 'header/reference'
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module Header
+        class << self
+          # Creates a header model or reference.
+          def new(keywords = {})
+            return Reference.new(keywords) if keywords.key?(:ref)
+
+            Model.new(keywords)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/openapi/info.rb

@@ -5,6 +5,8 @@ module Jsapi
     module OpenAPI
       # Represents an info object.
       class Info < Base
+        include Extensions
+
         ##
         # :attr: contact
         # The optional Contact object.
@@ -35,16 +37,16 @@ module Jsapi
         # The version of the API.
         attribute :version, String
 
-        # Returns a hash representing the info object.
+        # Returns a hash representing the \OpenAPI info object.
         def to_openapi(*)
-          {
+          with_openapi_extensions(
             title: title,
             version: version,
             description: description,
             termsOfService: terms_of_service,
             contact: contact&.to_openapi,
             license: license&.to_openapi
-          }.compact
+          )
         end
       end
     end

data/lib/jsapi/meta/openapi/license.rb

@@ -5,6 +5,8 @@ module Jsapi
     module OpenAPI
       # Represents a license object.
       class License < Base
+        include Extensions
+
         ##
         # :attr: name
         # The name of the license.
@@ -15,12 +17,9 @@ module Jsapi
         # The optional URL of the license.
         attribute :url, String
 
-        # Returns a hash representing the license object.
+        # Returns a hash representing the \OpenAPI license object.
         def to_openapi(*)
-          {
-            name: name,
-            url: url
-          }.compact
+          with_openapi_extensions(name: name, url: url)
         end
       end
     end

data/lib/jsapi/meta/openapi/link/model.rb

@@ -6,6 +6,8 @@ module Jsapi
       module Link
         # Represents a link object.
         class Model < Base
+          include Extensions
+
           ##
           # :attr: description
           # The optional description of the link.
@@ -31,15 +33,15 @@ module Jsapi
           # The optional Server object.
           attribute :server, Server
 
-          # Returns a hash representing the link object.
+          # Returns a hash representing the \OpenAPI link object.
           def to_openapi(*)
-            {
+            with_openapi_extensions(
               operationId: operation_id,
               parameters: parameters,
               requestBody: request_body,
               description: description,
               server: server&.to_openapi
-            }.compact
+            )
           end
         end
       end

data/lib/jsapi/meta/openapi/oauth_flow.rb

@@ -5,6 +5,8 @@ module Jsapi
     module OpenAPI
       # Represents an OAuth flow object.
       class OAuthFlow < Base
+        include Extensions
+
         class Scope < Base
           ##
           # :attr: description
@@ -35,14 +37,14 @@ module Jsapi
         # The token URL to be used for the flow.
         attribute :token_url, String
 
-        # Returns a hash representing the OAuth flow object.
+        # Returns a hash representing the \OpenAPI OAuth flow object.
         def to_openapi(version)
-          {
+          with_openapi_extensions(
             authorizationUrl: authorization_url,
             tokenUrl: token_url,
             refreshUrl: (refresh_url if version.major > 2),
             scopes: scopes.transform_values(&:description)
-          }.compact
+          )
         end
       end
     end