jsapi 0.9.0 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e68467f73e8f1e909a03cd8c50f16674231dc0d070f05a5368b84e0f75dedfe6
-  data.tar.gz: 6c0b1304cb7192d223f517d5233fd96fa13aad7e0affb6832f313088bc3b3993
+  metadata.gz: 59c9ddcd1965cd62ee1b1bbb0e7f066061eaef6a5f8217c69b6d86ee92230b4a
+  data.tar.gz: f02a5ff2b0d13ca4c238356b8d11473432ec71b12b40218639335f9f2f45f1da
 SHA512:
-  metadata.gz: 45b860d17ffc8f22cfbe4fca26d38e727ff87ddc93a959c6285fd1aaa8eb0de9c5e2a9c516f717f0f6d463b0bfe5c8708b9efa5bab5aa6b08eb642d90ee84d10
-  data.tar.gz: fe573b4b85e50373bd832f1ec3d4fdd9c11fe57bf42527fe80021d6c84d2271e01161b08cdedcee587a69bd43a28219562d36ed0c127197e4cbfe34e05902aca
+  metadata.gz: 4f8f331323ab4d88ba89133f37b0eee8fc6bdb1ab5159f3ce5885b7139d4376e74f6df42ed8232c6ea5c4cb7b373d8ea5a8c866c6833d23f5f1412f6a004ea14
+  data.tar.gz: f7061a754b6bbde17046b4cc4cb29eca42daede67f3978f474574c9389d555815e5e11f8f2af021f93985458511790699a64d8cd5fc95b03f421792dcd0dd4a5

data/lib/jsapi/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Jsapi
+  # Holds the \Jsapi configuration.
+  class Configuration
+    # The path where the API definitions are located relative to +Rails.root+.
+    # The default is <code>"app/api_defs"</code>.
+    attr_accessor :api_defs_path
+
+    def initialize # :nodoc:
+      @api_defs_path = 'app/api_defs'
+    end
+
+    # Returns the absolute +Pathname+ for +args+ within +api_defs_path+.
+    def pathname(*args)
+      return unless (root = Rails.root)
+
+      root.join(*[api_defs_path, args].flatten)
+    end
+  end
+
+  class << self
+    # The singleton \Jsapi configuration.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+  end
+end

data/lib/jsapi/controller/methods.rb

@@ -162,7 +162,7 @@ module Jsapi
         (operation.model || Model::Base).new(
           Parameters.new(
             params.except(:action, :controller, :format).permit!,
-            headers,
+            request.headers,
             operation,
             definitions,
             strong: strong

data/lib/jsapi/dsl/base.rb

@@ -3,9 +3,26 @@
 module Jsapi
   module DSL
     class Base
-      def initialize(meta_model, &block)
+      def initialize(meta_model, pathname = nil, parent: nil, &block)
         @meta_model = meta_model
+        @pathname = pathname
+        @parent = parent
 
+        # Raise an error when pathname is attempted to be imported again
+        if pathname && (ancestor = parent)
+          while ancestor
+            if ancestor.pathname == pathname
+              raise Error, "Attempted #{pathname.to_path.inspect} to be imported again"
+            end
+
+            ancestor = ancestor.parent
+          end
+        end
+
+        # Evaluate the file to be imported
+        instance_eval(pathname.read, pathname.to_path) if pathname
+
+        # Evaluate block
         if block
           if meta_model.reference?
             raise Error, "reference can't be specified together with a block"
@@ -15,10 +32,30 @@ module Jsapi
         end
       end
 
+      # Imports the file named +filename+ relative to +Jsapi.configation.path+.
+      def import(filename)
+        raise ArgumentError, "file name can't be blank" if filename.blank?
+
+        pathname = Jsapi.configuration.pathname("#{filename}.rb")
+        self.class.new(@meta_model, pathname, parent: self)
+      end
+
+      # Imports the file named +filename+ relative to the current file's path.
+      def import_relative(filename)
+        raise ArgumentError, "file name can't be blank" if filename.blank?
+
+        pathname = (@pathname&.parent || Jsapi.configuration.pathname) + "#{filename}.rb"
+        self.class.new(@meta_model, pathname, parent: self)
+      end
+
       def respond_to_missing?(*args) # :nodoc:
         keyword?(args.first)
       end
 
+      protected
+
+      attr_reader :parent, :pathname
+
       private
 
       def define(*args, &block)

data/lib/jsapi/dsl/class_methods.rb

@@ -29,13 +29,29 @@ module Jsapi
         api_definitions { default(type, **keywords, &block) }
       end
 
-      # The API definitions of the current class.
-      def api_definitions(&block)
-        @api_definitions ||= Meta::Definitions.new(
-          owner: self,
-          parent: superclass.try(:api_definitions)
-        )
+      # Returns the API definitions associated with the current class. Adds additional
+      # definitions when any keywords or a block is specified.
+      #
+      #   api_definitions base_path: '/foo' do
+      #     operation 'bar'
+      #   end
+      def api_definitions(**keywords, &block)
+        unless defined? @api_definitions
+          @api_definitions = Meta::Definitions.new(
+            owner: self,
+            parent: superclass.try(:api_definitions)
+          )
+          if (name = try(:name))
+            pathname = Jsapi.configuration.pathname(
+              name.deconstantize.split('::').map(&:underscore),
+              "#{name.demodulize.delete_suffix('Controller').underscore}.rb"
+            )
+            Definitions.new(@api_definitions, pathname) if pathname&.file?
+          end
+        end
+        @api_definitions.merge!(keywords) if keywords.any?
         Definitions.new(@api_definitions, &block) if block
+
         @api_definitions
       end
 
@@ -71,6 +87,11 @@ module Jsapi
         api_definitions { host(arg) }
       end
 
+      # Imports the file named +filename+ relative to +Jsapi.configation.path+.
+      def api_import(filename)
+        api_definitions { import(filename) }
+      end
+
       # Includes API definitions from +klasses+.
       def api_include(*klasses)
         api_definitions { include(*klasses) }

data/lib/jsapi/dsl/definitions.rb

@@ -218,7 +218,7 @@ module Jsapi
       ##
       # :method: security_requirement
       # :args: **keywords, &block
-      # Adds a security requirement.
+      # Specifies a security requirement.
       #
       #   security_requirement do
       #     scheme 'basic_auth'

data/lib/jsapi/dsl/operation.rb

@@ -38,6 +38,15 @@ module Jsapi
       #
       #   deprecated true
 
+      ##
+      # :method: external_docs
+      # :args: **keywords, &block
+      # Specifies the external documentation.
+      #
+      #    external_docs url: 'https://foo.bar/docs'
+      #
+      # See Meta::Operation#external_docs for further information.
+
       ##
       # :method: description
       # :args: arg
@@ -162,6 +171,17 @@ module Jsapi
         end
       end
 
+      ##
+      # :method: security_requirement
+      # :args: **keywords, &block
+      # Specifies a security requirement.
+      #
+      #   security_requirement do
+      #     scheme 'basic_auth'
+      #   end
+      #
+      # See Meta::Operation#security_requirements for further information.
+
       ##
       # :method: summary
       # :args: arg

data/lib/jsapi/dsl/schema.rb

@@ -5,6 +5,15 @@ module Jsapi
     # Used to define a schema.
     class Schema < Base
 
+      ##
+      # :method: additional_properties
+      # :args: **keywords, &block
+      # Specifies the schema of properties that are not explicity specified.
+      #
+      #   additional_properties type: 'string'
+      #
+      # See Meta::Schema::Object#additional_properties for further information.
+
       # Includes all of the properties from +schemas+. Each argument must be the name of
       # a schema defined by ClassMethods#api_schema or Definitions#schema.
       def all_of(*schemas)
@@ -47,8 +56,9 @@ module Jsapi
       #
       #   enum %w[foo bar]
 
-      ## :method: external_docs
-      ## :args: **keywords, &blocks
+      ##
+      # :method: external_docs
+      # :args: **keywords, &block
       # Specifies the external documentation.
       #
       # See Meta::Schema::Base#external_docs for further information.

data/lib/jsapi/meta/callback/reference.rb

@@ -3,6 +3,7 @@
 module Jsapi
   module Meta
     module Callback
+      # Specifies a callback reference.
       class Reference < Base::Reference
         # Returns a hash representing the \OpenAPI reference object.
         def to_openapi(*)

data/lib/jsapi/meta/definitions.rb

@@ -382,10 +382,14 @@ module Jsapi
         @objects ||= ancestors.each_with_object({}) do |ancestor, objects|
           self.class.attribute_names.each do |key|
             case value = ancestor.send(key)
-            when Hash
-              (objects[key] ||= {}).reverse_merge!(value)
             when Array
               (objects[key] ||= []).push(*value)
+            when Hash
+              if (hash = objects[key])
+                value.each { |k, v| hash[k] = v unless hash.key?(k) }
+              else
+                objects[key] = value.dup
+              end
             else
               objects[key] ||= value
             end

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

@@ -3,6 +3,7 @@
 module Jsapi
   module Meta
     module Example
+      # Specifies an example reference.
       class Reference < Base::Reference
         # Returns a hash representing the \OpenAPI reference object.
         def to_openapi(*)

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

@@ -3,6 +3,7 @@
 module Jsapi
   module Meta
     module Header
+      # Specifies a header reference.
       class Reference < Base::Reference
         # Returns a hash representing the \OpenAPI reference object.
         def to_openapi(*)

data/lib/jsapi/meta/link/reference.rb

@@ -3,6 +3,7 @@
 module Jsapi
   module Meta
     module Link
+      # Specifies a link reference.
       class Reference < Base::Reference
         # Returns a hash representing the \OpenAPI reference object.
         def to_openapi(*)

data/lib/jsapi/meta/operation.rb

@@ -2,7 +2,7 @@
 
 module Jsapi
   module Meta
-    # Defines an API operation.
+    # Specifies an API operation.
     class Operation < Base::Model
       include OpenAPI::Extensions
 

data/lib/jsapi/meta/parameter/model.rb

@@ -3,10 +3,10 @@
 module Jsapi
   module Meta
     module Parameter
-      # Defines a parameter.
+      # Specifies a parameter.
       class Model < Base::Model
-        include ToOpenAPI
         include OpenAPI::Extensions
+        include ToOpenAPI
 
         delegate_missing_to :schema
 

data/lib/jsapi/meta/parameter/reference.rb

@@ -3,12 +3,14 @@
 module Jsapi
   module Meta
     module Parameter
+      # Specifies a parameter reference.
       class Reference < Base::Reference
         include ToOpenAPI
 
-        # Returns an array of hashes. Each hash represents an \OpenAPI parameter object
-        # if the type of the referred parameter is <code>"object"</code>. Otherwise the
-        # array contains a single hash representing the \OpenAPI reference object.
+        # Returns an array of hashes. If the type of the referred parameter is
+        # <code>"object"</code>, each hash represents an \OpenAPI parameter object.
+        # Otherwise the array contains a single hash representing the \OpenAPI
+        # reference object.
         #
         # Raises a ReferenceError when the reference could not be resolved.
         def to_openapi_parameters(version, definitions)

data/lib/jsapi/meta/parameter/to_openapi.rb

@@ -4,6 +4,7 @@ module Jsapi
   module Meta
     module Parameter
       module ToOpenAPI
+        # Returns a hash representing the \OpenAPI parameter or reference object.
         def to_openapi(version, definitions)
           to_openapi_parameters(version, definitions).first
         end

data/lib/jsapi/meta/property.rb

@@ -2,6 +2,7 @@
 
 module Jsapi
   module Meta
+    # Specifies a property
     class Property < Base::Model
       delegate_missing_to :schema
 

data/lib/jsapi/meta/request_body/model.rb

@@ -3,7 +3,7 @@
 module Jsapi
   module Meta
     module RequestBody
-      # Defines a request body.
+      # Specifies a request body.
       class Model < Base::Model
         include OpenAPI::Extensions
 

data/lib/jsapi/meta/request_body/reference.rb

@@ -3,6 +3,7 @@
 module Jsapi
   module Meta
     module RequestBody
+      # Specifies a request body reference.
       class Reference < Base::Reference
         # Returns a hash representing the \OpenAPI reference object.
         def to_openapi(*)

data/lib/jsapi/meta/response/model.rb

@@ -3,7 +3,7 @@
 module Jsapi
   module Meta
     module Response
-      # Defines a response.
+      # Specifies a response.
       class Model < Base::Model
         include OpenAPI::Extensions
 

data/lib/jsapi/meta/response/reference.rb

@@ -3,6 +3,7 @@
 module Jsapi
   module Meta
     module Response
+      # Specifies a response reference.
       class Reference < Base::Reference
         # Returns a hash representing the \OpenAPI reference object.
         def to_openapi(version, *)

data/lib/jsapi/version.rb

@@ -5,6 +5,6 @@ module Jsapi
     # NOTE: See https://bundler.io/guides/creating_gem.html
 
     # The current GEM version.
-    VERSION = '0.9.0'
+    VERSION = '0.9.2'
   end
 end

data/lib/jsapi.rb

@@ -3,7 +3,7 @@
 require 'jsapi/invalid_value_helper'
 require 'jsapi/invalid_value_error'
 require 'jsapi/invalid_argument_error'
-
+require 'jsapi/configuration'
 require 'jsapi/model'
 require 'jsapi/meta'
 require 'jsapi/dsl'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsapi
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.2
 platform: ruby
 authors:
 - Denis Göller
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-12 00:00:00.000000000 Z
+date: 2024-10-24 00:00:00.000000000 Z
 dependencies: []
 description:
 email: denis@dmgoeller.de
@@ -17,6 +17,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/jsapi.rb
+- lib/jsapi/configuration.rb
 - lib/jsapi/controller.rb
 - lib/jsapi/controller/base.rb
 - lib/jsapi/controller/error.rb