jsapi 0.9.2 → 1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59c9ddcd1965cd62ee1b1bbb0e7f066061eaef6a5f8217c69b6d86ee92230b4a
-  data.tar.gz: f02a5ff2b0d13ca4c238356b8d11473432ec71b12b40218639335f9f2f45f1da
+  metadata.gz: a24c58c515109ade6015fbd712e6d08f8ea0dc3e1b747ecd1e2430de0ad157d2
+  data.tar.gz: 98112b68df57d56b51f9edcaa2283069481fb0c2a494cde18cb35d0205917423
 SHA512:
-  metadata.gz: 4f8f331323ab4d88ba89133f37b0eee8fc6bdb1ab5159f3ce5885b7139d4376e74f6df42ed8232c6ea5c4cb7b373d8ea5a8c866c6833d23f5f1412f6a004ea14
-  data.tar.gz: f7061a754b6bbde17046b4cc4cb29eca42daede67f3978f474574c9389d555815e5e11f8f2af021f93985458511790699a64d8cd5fc95b03f421792dcd0dd4a5
+  metadata.gz: e4e08e06bcfe77edb6b356a0f2aa00bc141bf1aae3c1fac09fdb61be36b7be27b24a8c698fcad63374936d2defa345cbb9328f5a6f486a9816ae21be0cd52853
+  data.tar.gz: 8b671d32824bdb6e924fd7bd11f16c3baeac90c8bd3ef7a3796d8a8220b574740f750cad6e79f986f4950b8659ca9bb151ad95d6cfe63beb95e6ed63e76e4a3a

data/lib/jsapi/controller/methods.rb

@@ -15,7 +15,7 @@ module Jsapi
       # 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.
+      # specification when the content type is a JSON MIME type.
       #
       #   api_operation('foo') do |api_params|
       #     # ...
@@ -151,9 +151,11 @@ module Jsapi
 
           Error.new(e, status: status)
         end
-        response = Response.new(result, response_model, definitions, omit: omit)
 
         # Write response
+        return unless response_model.json_type?
+
+        response = Response.new(result, response_model, definitions, omit: omit)
         self.content_type = response_model.content_type
         render(json: response, status: status)
       end

data/lib/jsapi/meta/callback/{model.rb → base.rb}

@@ -2,16 +2,14 @@
 
 module Jsapi
   module Meta
-    class Operation < Base::Model; end
+    class Operation < Model::Base; end
 
     module Callback
-      # Specifies a callback object. Applies to \OpenAPI 3.0 and higher.
-      class Model < Base::Model
+      # Specifies a callback. Applies to \OpenAPI 3.0 and higher.
+      class Base < Model::Base
         ##
         # :attr: operations
-        attribute :operations, { String => Operation }
-
-        undef add_operation
+        attribute :operations, { String => Operation }, accessors: %i[reader writer]
 
         # Adds a callback operation.
         #

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

@@ -3,13 +3,8 @@
 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(*)
-          { '$ref': "#/components/callbacks/#{ref}" }
-        end
-      end
+      # Refers a reusable callback.
+      class Reference < Model::Reference; end
     end
   end
 end

data/lib/jsapi/meta/callback.rb

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

data/lib/jsapi/meta/contact.rb

@@ -2,8 +2,8 @@
 
 module Jsapi
   module Meta
-    # Specifies a contact object.
-    class Contact < Base::Model
+    # Specifies a contact.
+    class Contact < Model::Base
       include OpenAPI::Extensions
 
       ##

data/lib/jsapi/meta/defaults.rb

@@ -3,7 +3,7 @@
 module Jsapi
   module Meta
     # Holds the default values for a particular Schema type.
-    class Defaults < Base::Model
+    class Defaults < Model::Base
       ##
       # :attr: within_requests
       # The default value of parameters and properties when reading requests.

data/lib/jsapi/meta/definitions.rb

@@ -2,7 +2,7 @@
 
 module Jsapi
   module Meta
-    class Definitions < Base::Model
+    class Definitions < Model::Base
       include OpenAPI::Extensions
 
       ##
@@ -58,12 +58,12 @@ module Jsapi
       ##
       # :attr: operations
       # The Operation objects.
-      attribute :operations, { String => Operation }
+      attribute :operations, { String => Operation }, accessors: %i[reader writer]
 
       ##
       # :attr: parameters
       # The reusable Parameter objects.
-      attribute :parameters, { String => Parameter }
+      attribute :parameters, { String => Parameter }, accessors: %i[reader writer]
 
       ##
       # :attr: rescue_handlers
@@ -138,8 +138,6 @@ module Jsapi
         @parent&.inherited(self)
       end
 
-      undef add_operation, add_parameter
-
       def add_operation(name = nil, keywords = {}) # :nodoc:
         name = name.nil? ? default_operation_name : name.to_s
         keywords = keywords.reverse_merge(path: default_operation_path)
@@ -273,7 +271,7 @@ module Jsapi
           else
             {
               # Order according to the OpenAPI specification 3.x
-              openapi: version.minor.zero? ? '3.0.3' : '3.1.0',
+              openapi: version.minor.zero? ? '3.0.3' : '3.1.1',
               info: openapi_objects[:info],
               servers: openapi_objects[:servers] ||
                 [default_server&.to_openapi].compact.presence,

data/lib/jsapi/meta/example/{model.rb → base.rb}

@@ -3,8 +3,8 @@
 module Jsapi
   module Meta
     module Example
-      # Specifies an example object.
-      class Model < Base::Model
+      # Specifies an example.
+      class Base < Model::Base
         include OpenAPI::Extensions
 
         ##
@@ -29,11 +29,11 @@ module Jsapi
 
         # Returns a hash representing the \OpenAPI example object.
         def to_openapi(*)
-          with_openapi_extensions(summary: summary, description: description).tap do |hash|
+          with_openapi_extensions(summary: summary, description: description).tap do |result|
             if external?
-              hash[:external_value] = value
+              result[:external_value] = value
             else
-              hash[:value] = value
+              result[:value] = value
             end
           end
         end

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

@@ -3,13 +3,8 @@
 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(*)
-          { '$ref': "#/components/examples/#{ref}" }
-        end
-      end
+      # Refers a reusable example.
+      class Reference < Model::Reference; end
     end
   end
 end

data/lib/jsapi/meta/example.rb

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

data/lib/jsapi/meta/external_documentation.rb

@@ -2,8 +2,8 @@
 
 module Jsapi
   module Meta
-    # Specifies an external documentation object.
-    class ExternalDocumentation < Base::Model
+    # Specifies an external documentation.
+    class ExternalDocumentation < Model::Base
       include OpenAPI::Extensions
 
       ##

data/lib/jsapi/meta/header/{model.rb → base.rb}

@@ -3,8 +3,8 @@
 module Jsapi
   module Meta
     module Header
-      # Specifies a header object.
-      class Model < Base::Model
+      # Specifies an HTTP header.
+      class Base < Model::Base
         include OpenAPI::Extensions
 
         delegate_missing_to :schema
@@ -39,7 +39,7 @@ module Jsapi
         ##
         # :attr_reader: schema
         # The Schema of the header.
-        attribute :schema, read_only: true
+        attribute :schema, accessors: %i[reader]
 
         def initialize(keywords = {})
           raise ArgumentError, "type can't be object" if keywords[:type] == 'object'

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

@@ -3,13 +3,8 @@
 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(*)
-          { '$ref': "#/components/headers/#{ref}" }
-        end
-      end
+      # Refers a reusable header.
+      class Reference < Model::Reference; end
     end
   end
 end

data/lib/jsapi/meta/header.rb

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

data/lib/jsapi/meta/info.rb

@@ -2,13 +2,13 @@
 
 module Jsapi
   module Meta
-    # Specifies an info object.
-    class Info < Base::Model
+    # Specifies metadata about an API.
+    class Info < Model::Base
       include OpenAPI::Extensions
 
       ##
       # :attr: contact
-      # The Contact object.
+      # The Contact.
       attribute :contact, Contact
 
       ##
@@ -18,9 +18,14 @@ module Jsapi
 
       ##
       # :attr: license
-      # The License object.
+      # The License.
       attribute :license, License
 
+      ##
+      # :attr: summary
+      # The short summary of the API. Applies to \OpenAPI 3.1 and higher.
+      attribute :summary, String
+
       ##
       # :attr: terms_of_service
       # The URL pointing to the terms of service.
@@ -37,14 +42,17 @@ module Jsapi
       attribute :version, String
 
       # Returns a hash representing the \OpenAPI info object.
-      def to_openapi(*)
+      def to_openapi(version, *)
+        version = OpenAPI::Version.from(version)
+
         with_openapi_extensions(
           title: title,
-          version: version,
+          summary: (summary if version >= OpenAPI::V3_1),
           description: description,
           termsOfService: terms_of_service,
           contact: contact&.to_openapi,
-          license: license&.to_openapi
+          license: license&.to_openapi(version),
+          version: self.version
         )
       end
     end

data/lib/jsapi/meta/license.rb

@@ -2,10 +2,15 @@
 
 module Jsapi
   module Meta
-    # Specifies a license object.
-    class License < Base::Model
+    # Specifies a license.
+    class License < Model::Base
       include OpenAPI::Extensions
 
+      ##
+      # :attr: identifier
+      # The SDPX identifier of the license. Applies to \OpenAPI 3.1 and higher.
+      attribute :identifier, String, accessors: %i[reader]
+
       ##
       # :attr: name
       # The name of the license.
@@ -14,11 +19,29 @@ module Jsapi
       ##
       # :attr: url
       # The URL of the license.
-      attribute :url, String
+      attribute :url, String, accessors: %i[reader]
+
+      def identifier=(identifier) # :nodoc:
+        raise 'identifier and url are mutually exclusive' if url.present?
+
+        @identifier = identifier
+      end
+
+      def url=(url) # :nodoc:
+        raise 'identifier and url are mutually exclusive' if identifier.present?
+
+        @url = url
+      end
 
       # Returns a hash representing the \OpenAPI license object.
-      def to_openapi(*)
-        with_openapi_extensions(name: name, url: url)
+      def to_openapi(version, *)
+        version = OpenAPI::Version.from(version)
+
+        with_openapi_extensions(
+          name: name,
+          identifier: (identifier if version >= OpenAPI::V3_1),
+          url: url
+        )
       end
     end
   end

data/lib/jsapi/meta/link/{model.rb → base.rb}

@@ -3,8 +3,8 @@
 module Jsapi
   module Meta
     module Link
-      # Specifies a link object.
-      class Model < Base::Model
+      # Specifies a link.
+      class Base < Model::Base
         include OpenAPI::Extensions
 
         ##

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

@@ -3,13 +3,8 @@
 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(*)
-          { '$ref': "#/components/links/#{ref}" }
-        end
-      end
+      # Refers a reusable link.
+      class Reference < Model::Reference; end
     end
   end
 end

data/lib/jsapi/meta/link.rb

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

data/lib/jsapi/meta/{base → model}/attributes.rb

@@ -2,17 +2,17 @@
 
 module Jsapi
   module Meta
-    module Base
+    module Model
       module Attributes
         DEFAULT_ARRAY = [].freeze
         DEFAULT_HASH = {}.freeze
 
         # Defines an attribute.
         def attribute(name, type = Object,
+                      accessors: %i[add reader writer],
                       default: nil,
                       default_key: nil,
                       keys: nil,
-                      read_only: false,
                       values: nil)
 
           (@attribute_names ||= []) << name.to_sym
@@ -24,10 +24,9 @@ module Jsapi
             # General default
             default ||= DEFAULT_ARRAY
 
-            unless read_only
+            if accessors.include?(:add) || accessors.include?(:writer)
               singular_name = name.to_s.singularize
               add_method = "add_#{singular_name}"
-
               type_caster = TypeCaster.new(type.first, values: values, name: singular_name)
 
               # Attribute writer
@@ -35,7 +34,7 @@ module Jsapi
                 instance_variable_set(instance_variable_name, []).tap do
                   Array.wrap(argument).each { |element| send(add_method, element) }
                 end
-              end
+              end if accessors.include?(:writer)
 
               # Add method
               define_method(add_method) do |argument = nil|
@@ -47,26 +46,24 @@ module Jsapi
                   end << casted_argument
                   attribute_changed(name)
                 end
-              end
+              end if accessors.include?(:add)
             end
           when Hash
-            singular_name = name.to_s.singularize
+            # General default
+            default ||= DEFAULT_HASH
 
+            singular_name = name.to_s.singularize
             key_type, value_type = type.first
             key_type_caster = TypeCaster.new(key_type, values: keys, name: 'key')
 
-            # General default
-            default ||= DEFAULT_HASH
-
             # Lookup method
             define_method(singular_name) do |key = nil|
               key = default_key if key.to_s.empty?
               send(name)[key_type_caster.cast(key)]
-            end
+            end if accessors.include?(:reader)
 
-            unless read_only
+            if accessors.include?(:add) || accessors.include?(:writer)
               add_method = "add_#{singular_name}"
-
               value_type_caster = TypeCaster.new(value_type, values: values)
 
               # Attribute writer
@@ -74,7 +71,7 @@ module Jsapi
                 instance_variable_set(instance_variable_name, {}).tap do
                   Hash(argument).each { |key, value| send(add_method, key, value) }
                 end
-              end
+              end if accessors.include?(:writer)
 
               # Add method
               define_method(add_method) do |key_or_value, value = nil|
@@ -98,16 +95,16 @@ module Jsapi
 
                 attribute_changed(name)
                 casted_value
-              end
+              end if accessors.include?(:add)
             end
           else
             # Predicate method
             define_method("#{name}?") do
               value = instance_variable_get(instance_variable_name)
               value.nil? ? default || false : value
-            end if values == [true, false]
+            end if values == [true, false] && accessors.include?(:reader)
 
-            unless read_only
+            if accessors.include?(:writer)
               type_caster = TypeCaster.new(type, values: values, name: name)
 
               # Attribute writer
@@ -124,7 +121,7 @@ module Jsapi
           define_method(name) do
             value = instance_variable_get(instance_variable_name)
             value.nil? ? default : value
-          end
+          end if accessors.include?(:reader)
         end
 
         def attribute_names

data/lib/jsapi/meta/{base/model.rb → model/base.rb}

@@ -2,9 +2,9 @@
 
 module Jsapi
   module Meta
-    module Base
+    module Model
       # The base meta model class.
-      class Model
+      class Base
         extend Attributes
 
         # Creates a new meta model.

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Model
+      # The base reference class.
+      class Reference < Base
+        # Derrives the component type from the inner most module name.
+        def self.component_type
+          @component_type ||= name.split('::')[-2].underscore
+        end
+
+        # Derrives the \OpenAPI component type from the inner most module name.
+        def self.openapi_component_type
+          @openapi_component_type ||= name.split('::')[-2].pluralize.camelize(:lower)
+        end
+
+        ##
+        # :attr: description
+        # The description to be displayed instead of the description of the referred object.
+        # Applies to \OpenAPI 3.1 and higher.
+        attribute :description, String
+
+        ##
+        # :attr: ref
+        # The name of the referred object.
+        attribute :ref, String
+
+        ##
+        # :attr: summary
+        # The summary to be displayed instead of the summary of the referred object.
+        # Applies to \OpenAPI 3.1 and higher.
+        attribute :summary, String
+
+        # Returns true.
+        def reference?
+          true
+        end
+
+        # Resolves +ref+ by looking up the object with that name in +definitions+.
+        #
+        # Raises a ReferenceError if +ref+ could not be resolved.
+        def resolve(definitions)
+          object = definitions.send("find_#{self.class.component_type}", ref)
+          raise ReferenceError, ref if object.nil?
+
+          object.resolve(definitions)
+        end
+
+        # Returns a hash representing the \OpenAPI reference object.
+        def to_openapi(version, *)
+          version = OpenAPI::Version.from(version)
+
+          { '$ref': "#/#{openapi_components_path(version)}/#{ref}" }.tap do |result|
+            if version >= OpenAPI::V3_1
+              result[:summary] = summary if summary
+              result[:description] = description if description
+            end
+          end
+        end
+
+        private
+
+        def openapi_components_path(version)
+          component_type = self.class.openapi_component_type
+
+          version.major == 2 ? component_type : "components/#{component_type}"
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/{base → model}/type_caster.rb

@@ -2,7 +2,7 @@
 
 module Jsapi
   module Meta
-    module Base
+    module Model
       class TypeCaster
         STRING_CASTER = ->(arg) { arg&.to_s } # :nodoc:
 

data/lib/jsapi/meta/model.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'model/type_caster'
+require_relative 'model/attributes'
+require_relative 'model/base'
+require_relative 'model/reference'