jsapi 2.1.2 → 3.0

data/lib/jsapi/{meta/definitions.rb → definition/api.rb}

@@ -1,13 +1,20 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
-    class Definitions < Model::Base
+  module Definition
+    # Raised when no operation with the specified name is found.
+    class OperationNotFound < StandardError
+      def initialize(operation_name)
+        super("operation not found: #{operation_name}")
+      end
+    end
+
+    class API < Model::Base
       include OpenAPI::Extensions
 
       ##
       # :attr: base_path
-      # The base path of the API.
+      # The base path of the \API.
       #
       # Applies to \OpenAPI 2.0.
       attribute :base_path, Pathname
@@ -46,7 +53,7 @@ module Jsapi
 
       ##
       # :attr: host
-      # The host serving the API.
+      # The host serving the \API.
       #
       # Applies to \OpenAPI 2.0.
       attribute :host, String
@@ -108,7 +115,7 @@ module Jsapi
 
       ##
       # :attr: schemes
-      # The transfer protocols supported by the API. Can contain one or more of:
+      # The transfer protocols supported by the \API. Can contain one or more of:
       #
       # - <code>"http"</code>
       # - <code>"https"</code>
@@ -132,7 +139,7 @@ module Jsapi
 
       ##
       # :attr: servers
-      # The servers providing the API.
+      # The servers providing the \API.
       #
       # Applies to \OpenAPI 3.0 and higher.
       attribute :servers, [Server]
@@ -145,7 +152,7 @@ module Jsapi
       # The class to which this instance is assigned.
       attr_reader :owner
 
-      # The +Definitions+ instance from which this instance inherits.
+      # The +API+ instance from which this instance inherits.
       attr_reader :parent
 
       def initialize(keywords = {})
@@ -155,8 +162,8 @@ module Jsapi
         included = keywords.delete(:include)
         super(keywords)
 
-        Array(included).each do |definitions|
-          include(definitions)
+        Array(included).each do |api|
+          include(api)
         end
         @parent&.inherited(self)
       end
@@ -188,12 +195,12 @@ module Jsapi
         end
       end
 
-      # Returns an array containing itself and all of the +Definitions+ instances
+      # Returns an array containing itself and all of the +API+ instances
       # inherited or included.
       def ancestors
         @ancestors ||= [self].tap do |ancestors|
-          [@included_definitions, @parent].flatten.each do |definitions|
-            ancestors.push(*definitions.ancestors) if definitions
+          [@included_apis, @parent].flatten.each do |api|
+            ancestors.push(*api.ancestors) if api
           end
         end.uniq
       end
@@ -229,8 +236,8 @@ module Jsapi
 
           cache_path_attribute(arg, name) do
             arg.ancestors.lazy.filter_map do |pathname|
-              ancestors.lazy.filter_map do |definitions|
-                definitions.path(pathname)&.public_send(name).presence
+              ancestors.lazy.filter_map do |api|
+                api.path(pathname)&.public_send(name).presence
               end.first
             end.first
           end
@@ -255,8 +262,8 @@ module Jsapi
 
           cache_path_attribute(arg, name) do
             arg.ancestors.flat_map do |pathname|
-              ancestors.filter_map do |definitions|
-                definitions.path(pathname)&.send(name)
+              ancestors.filter_map do |api|
+                api.path(pathname)&.send(name)
               end
             end.reduce({}, &:reverse_merge).presence
           end
@@ -280,8 +287,8 @@ module Jsapi
 
           cache_path_attribute(arg, name) do
             arg.ancestors.filter_map do |pathname|
-              ancestors.filter_map do |definitions|
-                definitions.path(pathname)&.send(name)
+              ancestors.filter_map do |api|
+                api.path(pathname)&.send(name)
               end
             end.flatten.uniq.presence
           end
@@ -298,7 +305,8 @@ module Jsapi
         cached_attributes[:security_requirements]
       end
 
-      # Returns the operation with the specified name.
+      # Returns the operation with the specified name or +nil+ if no such
+      # operation is found.
       def find_operation(name = nil)
         name = name&.to_s
 
@@ -313,6 +321,15 @@ module Jsapi
         end
       end
 
+      # Like +find_operation+, except that it raises an OperationNotFound error
+      # when no such operation is found.
+      def find_operation!(name = nil)
+        operation = find_operation(name)
+        return operation if operation
+
+        raise OperationNotFound.new(name)
+      end
+
       ##
       # :method: find_example
       # Returns the reusable example with the specified name.
@@ -344,17 +361,17 @@ module Jsapi
         end
       end
 
-      # Includes +definitions+.
-      def include(definitions)
-        if circular_dependency?(definitions)
+      # Includes +api+.
+      def include(api)
+        if circular_dependency?(api)
           raise ArgumentError,
                 'detected circular dependency between ' \
                 "#{owner.inspect} and " \
-                "#{definitions.owner.inspect}"
+                "#{api.owner.inspect}"
         end
 
-        (@included_definitions ||= []) << definitions
-        definitions.included(self)
+        (@included_apis ||= []) << api
+        api.included(self)
         invalidate_ancestors
         self
       end
@@ -497,37 +514,42 @@ module Jsapi
       end
 
       # Returns the first RescueHandler capable to handle +exception+, or nil
-      # if no one could be found.
+      # if no one is found.
       def rescue_handler_for(exception)
         cached_attributes[:rescue_handlers].find { |r| r.match?(exception) }
       end
 
+      # Returns the server with the specified name or +nil+ if no such server is present.
+      def server(name)
+        cached_attributes[:servers].find { |server| server.name == name } unless name.nil?
+      end
+
       protected
 
-      # The +Definitions+ instances that directly inherit from this instance.
+      # The +API+ instances that directly inherit from this instance.
       attr_reader :children
 
-      # The +Definitions+ instances that directly include this instance.
-      attr_reader :dependent_definitions
+      # The +API+ instances that directly include this instance.
+      attr_reader :dependent_apis
 
-      # The +Definitions+ instances included.
-      attr_reader :included_definitions
+      # The +API+ instances included.
+      attr_reader :included_apis
 
       def attribute_changed(*) # :nodoc:
         invalidate_attributes
         super
       end
 
-      # Invoked whenever it is included in another +Definitions+ instance.
-      def included(definitions)
-        (@dependent_definitions ||= []) << definitions
+      # Invoked whenever it is included in another +API+ instance.
+      def included(api)
+        (@dependent_apis ||= []) << api
       end
 
       # rubocop:disable Lint/MissingSuper
 
-      # Invoked whenever it is inherited by another +Definitions+ instance.
-      def inherited(definitions)
-        (@children ||= []) << definitions
+      # Invoked whenever it is inherited by another +API+ instance.
+      def inherited(api)
+        (@children ||= []) << api
       end
 
       # rubocop:enable Lint/MissingSuper
@@ -592,9 +614,9 @@ module Jsapi
 
       def circular_dependency?(other)
         return true if other == self
-        return false unless other.included_definitions&.any?
+        return false unless other.included_apis&.any?
 
-        other.included_definitions.any? { |included| circular_dependency?(included) }
+        other.included_apis.any? { |included| circular_dependency?(included) }
       end
 
       def default_operation_name
@@ -616,7 +638,7 @@ module Jsapi
       end
 
       def each_descendant(&block)
-        [*@children, *dependent_definitions].each(&block)
+        [*@children, *dependent_apis].each(&block)
         nil
       end
 

data/lib/jsapi/{meta → definition}/callable/symbol_evaluator.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     module Callable
       class SymbolEvaluator
         attr_reader :symbol

data/lib/jsapi/{meta → definition}/callable/symbol_sequence_evaluator.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     module Callable
       class SymbolSequenceEvaluator
         attr_reader :symbols

data/lib/jsapi/{meta → definition}/callable.rb

@@ -4,7 +4,7 @@ require_relative 'callable/symbol_evaluator'
 require_relative 'callable/symbol_sequence_evaluator'
 
 module Jsapi
-  module Meta
+  module Definition
     module Callable
       class << self
         def from(arg)

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     module Parameter; end
     class Operation < Model::Base; end
 
@@ -50,13 +50,13 @@ module Jsapi
 
           # Returns a hash representing the \OpenAPI path item object that describes
           # the operations.
-          def to_openapi(version, definitions)
+          def to_openapi(version, api)
             OpenAPI::PathItem.new(
               operations.values,
               description: description,
               summary: summary,
               parameters: parameters
-            ).to_openapi(version, definitions)
+            ).to_openapi(version, api)
           end
         end
 
@@ -76,9 +76,9 @@ module Jsapi
         end
 
         # Returns a hash representing the \OpenAPI callback object.
-        def to_openapi(version, definitions)
+        def to_openapi(version, api)
           expressions.transform_values do |operations|
-            operations.to_openapi(version, definitions)
+            operations.to_openapi(version, api)
           end
         end
       end

data/lib/jsapi/{meta → definition}/callback/reference.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     module Callback
       # Refers a reusable callback.
       class Reference < Model::Reference; end

data/lib/jsapi/{meta → definition}/callback.rb

@@ -4,7 +4,7 @@ require_relative 'callback/base'
 require_relative 'callback/reference'
 
 module Jsapi
-  module Meta
+  module Definition
     module Callback
       class << self
         # Creates a Base or Reference.

data/lib/jsapi/{meta → definition}/contact.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     # Specifies a contact.
     class Contact < Model::Base
       include OpenAPI::Extensions

data/lib/jsapi/{meta → definition}/content.rb

@@ -1,20 +1,20 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     # Specifies the content of a request body or response.
     class Content < Model::Base
       include OpenAPI::Extensions
 
       class Wrapper < Model::Wrapper
         def schema
-          @schema ||= Schema.wrap(super, definitions)
+          @schema ||= Schema.wrap(super, api)
         end
       end
 
       include Model::Wrappable
 
-      delegate_missing_to :schema
+      delegate_missing_to :schema, allow_nil: true
 
       ##
       # :attr: examples
@@ -33,20 +33,20 @@ module Jsapi
         add_example(value: keywords.delete(:example)) if keywords.key?(:example)
         keywords[:ref] = keywords.delete(:schema) if keywords.key?(:schema)
 
-        @schema = Schema.new(keywords)
+        @schema = Schema.new(keywords) if keywords[:type] || keywords[:ref]
       end
 
       # Returns the data value of the first example.
-      def example_data_value(definitions, locale: nil)
+      def example_data_value(api, locale: nil)
         examples
           .values.first
-          &.resolve(definitions)
-          &.data_value(builder: example_builder(definitions, locale))
+          &.resolve(api)
+          &.data_value(builder: example_builder(api, locale))
       end
 
       # Returns a hash representing the \OpenAPI media type object describing
       # the content. Applies to \OpenAPI 3.0 and higher.
-      def to_openapi(version, definitions = nil, locale: nil, media_type: nil)
+      def to_openapi(version, api = nil, locale: nil, media_type: nil)
         version = OpenAPI::Version.from(version)
         example_builder = nil
 
@@ -59,7 +59,7 @@ module Jsapi
             end,
           examples:
             examples.transform_values do |example|
-              example_builder ||= example_builder(definitions, locale)
+              example_builder ||= example_builder(api, locale)
               example.to_openapi(version, builder: example_builder)
             end.presence
         )
@@ -67,8 +67,8 @@ module Jsapi
 
       private
 
-      def example_builder(definitions, locale)
-        Example::Builder.new(schema, definitions, locale: locale) if definitions.present?
+      def example_builder(api, locale)
+        Example::Builder.new(schema, api, locale: locale) if api.present?
       end
     end
   end

data/lib/jsapi/{meta → definition}/defaults.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     # Holds the default values for a particular Schema type.
     class Defaults < Model::Base
       ##

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     module Example
       # Specifies an example.
       class Base < Model::Base

data/lib/jsapi/{meta → definition}/example/builder.rb

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     module Example
       class Builder # :nodoc:
-        def initialize(schema, definitions, locale: nil)
-          @schema = Schema.wrap(schema, definitions)
+        def initialize(schema, api, locale: nil)
+          @schema = Schema.wrap(schema, api)
           @locale = locale
         end
 
         def generate_json(object, omit: nil)
-          raise ArgumentError, Messages.invalid_value(
+          raise ArgumentError, Support::Messages.invalid_value(
             name: 'omit',
             value: omit,
             valid_values: %i[empty nil]

data/lib/jsapi/{meta → definition}/example/reference.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     module Example
       # Refers a reusable example.
       class Reference < Model::Reference; end

data/lib/jsapi/{meta → definition}/example.rb

@@ -5,7 +5,7 @@ require_relative 'example/builder'
 require_relative 'example/reference'
 
 module Jsapi
-  module Meta
+  module Definition
     module Example
       class << self
         # Creates a Base or Reference.

data/lib/jsapi/{meta → definition}/existence.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     # Combines the presence concepts of the +#present?+ method and \JSON \Schema
     # by four levels of existence.
     class Existence

data/lib/jsapi/{meta → definition}/external_documentation.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     # Specifies an external documentation.
     class ExternalDocumentation < Model::Base
       include OpenAPI::Extensions

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     module Header
       # Specifies an HTTP header.
       class Base < Model::Base

data/lib/jsapi/{meta → definition}/header/reference.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     module Header
       # Refers a reusable header.
       class Reference < Model::Reference; end

data/lib/jsapi/{meta → definition}/header.rb

@@ -4,7 +4,7 @@ require_relative 'header/base'
 require_relative 'header/reference'
 
 module Jsapi
-  module Meta
+  module Definition
     module Header
       class << self
         # Creates a Base or Reference.

data/lib/jsapi/{meta → definition}/info.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     # Specifies metadata about an API.
     class Info < Model::Base
       include OpenAPI::Extensions

data/lib/jsapi/{meta → definition}/license.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     # Specifies a license.
     class License < Model::Base
       include OpenAPI::Extensions

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     module Link
       # Specifies a link.
       class Base < Model::Base

data/lib/jsapi/{meta → definition}/link/reference.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     module Link
       # Refers a reusable link.
       class Reference < Model::Reference; end

data/lib/jsapi/{meta → definition}/link.rb

@@ -4,7 +4,7 @@ require_relative 'link/base'
 require_relative 'link/reference'
 
 module Jsapi
-  module Meta
+  module Definition
     module Link
       class << self
         # Creates a Base or Reference.

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     module Model
       module Attributes
         module ClassMethods

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     module Model
       module Attributes
         # Raised when trying to modify a frozen attribute.

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     module Model
       module Attributes
         class TypeCaster
@@ -43,7 +43,7 @@ module Jsapi
             casted_value = @caster.call(value)
             return casted_value unless @values&.exclude?(casted_value)
 
-            raise ArgumentError, Messages.invalid_value(
+            raise ArgumentError, Support::Messages.invalid_value(
               name: @name,
               value: casted_value,
               valid_values: @values

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

@@ -5,7 +5,7 @@ require_relative 'attributes/type_caster'
 require_relative 'attributes/class_methods'
 
 module Jsapi
-  module Meta
+  module Definition
     module Model
       module Attributes
         def self.included(base) # :nodoc:

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Jsapi
-  module Meta
+  module Definition
     module Model
       # The base meta model class.
       class Base