jsapi 0.9.1 → 1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4631e17cbd92a36a62ab6e7aa139b65afa83fccc2c41da34c3f757f2b077340f
-  data.tar.gz: 4c547aeb52a0fc74c09389f2c97dd0b8c90883fd36c79b9c502689a25379f3f5
+  metadata.gz: d62e2c954028d8795f7e82dc2f0cde0310120f7e2a545102f53acefb42bfc603
+  data.tar.gz: ed65cf2695f95d4ff4622680ac54c601620974997f5cd2b5408fbe3deee62aef
 SHA512:
-  metadata.gz: 1db64f601b34597e5b13ee820482c5a72d2adef153feac7ef3e1141804df36cc8816f665ee18c73e1b30e50a8c13454bed4c7562d447b2fdaf1b3814d863bd09
-  data.tar.gz: a4bd27f4fcc7c50ee9447e70777ca54de3e81ee6fd7ab3124817baf54511c90d0d95cf461c09c7fdc42a3bf8b57bb62d91954bc96d8a44a77eb15f9d53d2f5be
+  metadata.gz: f2cca6b7b9a4d37979d7350ed24b171c0557e11d13968bea7cc7d7ca39418d4cfa39099b68fcf9a00249151f27362e677318ab8223c64d66cbf20ca9b6576045
+  data.tar.gz: cca09add16c901c819327e5391ab7a7d627434c3c1e4efdb6802fde5e053741b955748bce4708d0bcf8bee9ef46c9babf60949ef3d6f726e5f5f7feca7ef5d85

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/{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,12 +3,8 @@
 module Jsapi
   module Meta
     module Callback
-      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,
@@ -382,10 +380,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/{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,12 +3,8 @@
 module Jsapi
   module Meta
     module Example
-      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,12 +3,8 @@
 module Jsapi
   module Meta
     module Header
-      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,12 +3,8 @@
 module Jsapi
   module Meta
     module Link
-      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.