jsapi 0.8.0 → 0.9.0

data/lib/jsapi/meta/definitions.rb

@@ -3,89 +3,146 @@
 module Jsapi
   module Meta
     class Definitions < Base::Model
+      include OpenAPI::Extensions
+
       ##
-      # :attr_reader: children
-      # The +Definitions+ instances that directly inherit from this instance.
-      attribute :children, read_only: true, default: []
+      # :attr: base_path
+      # The base path of the API. Applies to \OpenAPI 2.0.
+      attribute :base_path, String
+
+      ##
+      # :attr: callbacks
+      # The reusable Callback objects. Applies to \OpenAPI 3.0 and higher.
+      attribute :callbacks, { String => Callback }
 
       ##
       # :attr: defaults
       # The Defaults.
-      attribute :defaults, { String => Defaults }, keys: Schema::TYPES, default: {}
+      attribute :defaults, { String => Defaults }, keys: Schema::TYPES
 
       ##
-      # :attr: dependent_definitions
-      # The +Definitions+ instances that directly include this instance.
-      attribute :dependent_definitions, read_only: true, default: []
+      # :attr: examples
+      # The reusable Example objects. Applies to \OpenAPI 3.0 and higher.
+      attribute :examples, { String => Example }
 
       ##
-      # :attr: included_definitions
-      # The +Definitions+ instances included.
-      attribute :included_definitions, [Definitions], add_method: :include, default: []
+      # :attr: external_docs
+      # The ExternalDocumentation object.
+      attribute :external_docs, ExternalDocumentation
 
       ##
-      # :attr: on_rescues
-      # The methods or procs to be called whenever an exception is rescued.
-      attribute :on_rescues, [], default: []
+      # :attr: headers
+      # The reusable Header objects. Applies to \OpenAPI 3.0 and higher.
+      attribute :headers, { String => Header }
 
       ##
-      # :attr: openapi
-      # The OpenAPI root object.
-      attribute :openapi, OpenAPI
+      # :attr: host
+      # The host serving the API. Applies to \OpenAPI 2.0.
+      attribute :host, String
 
       ##
-      # :attr: operations
-      # The Operation objects.
-      attribute :operations, { String => Operation }, default: {}
+      # :attr: info
+      # The Info object.
+      attribute :info, Info
 
       ##
-      # :attr_reader: owner
-      # The class to which this instance is assigned.
-      attribute :owner, read_only: true
+      # :attr: links
+      # The reusable Link objects. Applies to \OpenAPI 3.0 and higher.
+      attribute :links, { String => Link }
 
       ##
-      # :attr: parameters
-      # The reusable Parameter objects.
-      attribute :parameters, { String => Parameter }, default: {}
+      # :attr: on_rescues
+      # The methods or procs to be called whenever an exception is rescued.
+      attribute :on_rescues, []
 
       ##
-      # :attr_reader: parent
-      # The +Definitions+ instance from which this instance inherits.
-      attribute :parent, read_only: true
+      # :attr: operations
+      # The Operation objects.
+      attribute :operations, { String => Operation }
+
+      ##
+      # :attr: parameters
+      # The reusable Parameter objects.
+      attribute :parameters, { String => Parameter }
 
       ##
       # :attr: rescue_handlers
       # The RescueHandler objects.
-      attribute :rescue_handlers, [RescueHandler], default: []
+      attribute :rescue_handlers, [RescueHandler]
 
       ##
       # :attr: request_bodies
       # The reusable RequestBody objects.
-      attribute :request_bodies, { String => RequestBody }, default: {}
+      attribute :request_bodies, { String => RequestBody }
 
       ##
       # :attr: responses
       # The reusable Response objects.
-      attribute :responses, { String => Response }, default: {}
+      attribute :responses, { String => Response }
 
       ##
       # :attr: schemas
       # The reusable Schema objects.
-      attribute :schemas, { String => Schema }, default: {}
+      attribute :schemas, { String => Schema }
+
+      ##
+      # :attr: schemes
+      # The array of transfer protocols supported by the API. Possible values are:
+      #
+      # - <code>"http"</code>
+      # - <code>"https"</code>
+      # - <code>"ws"</code>
+      # - <code>"wss"</code>
+      #
+      # Applies to \OpenAPI 2.0.
+      attribute :schemes, [String], values: %w[http https ws wss]
+
+      ##
+      # :attr: security_requirements
+      # The array of SecurityRequirement objects.
+      attribute :security_requirements, [SecurityRequirement]
 
-      undef add_operation, add_parameter, include
+      alias add_security add_security_requirement
+
+      ##
+      # :attr: security_schemes
+      # The SecurityScheme objects.
+      attribute :security_schemes, { String => SecurityScheme }
+
+      ##
+      # :attr: servers
+      # The array of Server objects. Applies to \OpenAPI 3.0 and higher.
+      attribute :servers, [Server]
+
+      ##
+      # :attr: tags
+      # The array of Tag objects.
+      attribute :tags, [Tag]
+
+      # The class to which this instance is assigned.
+      attr_reader :owner
+
+      # The +Definitions+ instance from which this instance inherits.
+      attr_reader :parent
 
       def initialize(keywords = {})
+        keywords = keywords.dup
         @owner = keywords.delete(:owner)
         @parent = keywords.delete(:parent)
+        included = keywords.delete(:include)
         super(keywords)
 
+        Array(included).each do |definitions|
+          include(definitions)
+        end
         @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_path)
+        keywords = keywords.reverse_merge(path: default_operation_path)
         (@operations ||= {})[name] = Operation.new(name, keywords)
       end
 
@@ -98,20 +155,20 @@ module Jsapi
       # inherited/included.
       def ancestors
         @ancestors ||= [self].tap do |ancestors|
-          (included_definitions + Array(parent)).each do |definitions|
-            ancestors.push(*definitions.ancestors)
+          [@included_definitions, @parent].flatten.each do |definitions|
+            ancestors.push(*definitions.ancestors) if definitions
           end
         end.uniq
       end
 
       # Returns the default value for +type+ within +context+.
       def default_value(type, context: nil)
-        components.dig(:defaults, type.to_s)&.value(context: context)
+        objects.dig(:defaults, type.to_s)&.value(context: context)
       end
 
       # Returns the operation with the specified name.
       def find_operation(name = nil)
-        return components.dig(:operations, name.to_s) if name.present?
+        return objects.dig(:operations, name.to_s) if name.present?
 
         # Return the one and only operation
         operations.values.first if operations.one?
@@ -119,46 +176,43 @@ module Jsapi
 
       # Returns the reusable parameter with the specified name.
       def find_parameter(name)
-        components.dig(:parameters, name&.to_s)
+        objects.dig(:parameters, name&.to_s)
       end
 
       # Returns the reusable request body with the specified name.
       def find_request_body(name)
-        components.dig(:request_bodies, name&.to_s)
+        objects.dig(:request_bodies, name&.to_s)
       end
 
       # Returns the reusable response with the specified name.
       def find_response(name)
-        components.dig(:responses, name&.to_s)
+        objects.dig(:responses, name&.to_s)
       end
 
       # Returns the reusable schema with the specified name.
       def find_schema(name)
-        components.dig(:schemas, name&.to_s)
+        objects.dig(:schemas, name&.to_s)
       end
 
       # Includes +definitions+.
       def include(definitions)
         if circular_dependency?(definitions)
-          raise ArgumentError, 'detected circular dependency between ' \
-                               "#{owner.inspect} and " \
-                               "#{definitions.owner.inspect}"
+          raise ArgumentError,
+                'detected circular dependency between ' \
+                "#{owner.inspect} and " \
+                "#{definitions.owner.inspect}"
         end
 
         (@included_definitions ||= []) << definitions
         definitions.included(self)
-        attribute_changed(:included_definitions)
+        invalidate_ancestors
         self
       end
 
-      def inspect(*attributes) # :nodoc:
-        super(*(attributes.presence || %i[owner]))
-      end
-
       # Returns a hash representing the \JSON \Schema document for +name+.
       def json_schema_document(name)
         find_schema(name)&.to_json_schema&.tap do |json_schema_document|
-          if (schemas = components[:schemas].except(name.to_s)).any?
+          if (schemas = objects[:schemas].except(name.to_s)).any?
             json_schema_document[:definitions] = schemas.transform_values(&:to_json_schema)
           end
         end
@@ -166,7 +220,7 @@ module Jsapi
 
       # Returns the methods or procs to be called when rescuing an exception.
       def on_rescue_callbacks
-        components[:on_rescues]
+        objects[:on_rescues]
       end
 
       # Returns a hash representing the \OpenAPI document for +version+.
@@ -174,72 +228,94 @@ module Jsapi
       # Raises an +ArgumentError+ if +version+ is not supported.
       def openapi_document(version = nil)
         version = OpenAPI::Version.from(version)
-        operations = components[:operations].values
-
-        component_keys = %i[parameters responses parameters schemas]
-        component_keys.insert(3, :request_bodies) if version.major > 2
-
-        openapi_components = component_keys.filter_map do |key|
-          value = components[key].transform_values do |component|
-            case key
-            when :parameters
-              component.to_openapi(version, self).first
-            when :responses
-              component.to_openapi(version, self)
-            else
-              component.to_openapi(version)
+        operations = objects[:operations].values
+
+        openapi_paths =
+          operations.group_by { |operation| operation.path || default_operation_path }
+                    .transform_values do |operations_by_path|
+            operations_by_path.index_by(&:method).transform_values do |operation|
+              operation.to_openapi(version, self)
             end
           end.presence
 
-          [key, value] if value.present?
-        end.to_h
-
-        (openapi&.to_openapi(version, self) || {}).tap do |openapi_document|
-          openapi_document[:paths] =
-            operations
-            .group_by { |operation| operation.path || default_path }
-            .transform_values do |operations_by_path|
-              operations_by_path.index_by(&:method).transform_values do |operation|
-                operation.to_openapi(version, self)
-              end
-            end.presence
-
+        openapi_objects =
           if version.major == 2
-            consumes = operations.filter_map { |operation| operation.consumes(self) }
-            produces = operations.flat_map { |operation| operation.produces(self) }
-
-            openapi_document.merge!(
-              consumes: (consumes.uniq.sort if consumes.present?),
-              produces: (produces.uniq.sort if produces.present?),
-              definitions: openapi_components[:schemas],
-              parameters: openapi_components[:parameters],
-              responses: openapi_components[:responses]
-            )
-          elsif openapi_components.any?
-            (openapi_document[:components] ||= {}).reverse_merge!(
-              openapi_components.transform_keys do |key|
-                key.to_s.camelize(:lower).to_sym
-              end
-            )
-          end
-        end.compact
+            %i[base_path external_docs info host parameters responses parameters schemas
+               schemes security_requirements security_schemes tags]
+          else
+            %i[callbacks examples external_docs headers info links parameters request_bodies
+               responses schemas security_requirements security_schemes servers tags]
+          end.to_h { |key| [key, object_to_openapi(objects[key], version).presence] }
+
+        with_openapi_extensions(
+          if version.major == 2
+            openapi_server = objects[:servers].first || default_server
+            uri = URI(openapi_server.url) if openapi_server
+            {
+              # Order according to the OpenAPI specification 2.x
+              swagger: '2.0',
+              info: openapi_objects[:info],
+              host: openapi_objects[:host] || uri&.hostname,
+              basePath: openapi_objects[:base_path] || uri&.path,
+              schemes: openapi_objects[:schemes] || Array(uri&.scheme).presence,
+              consumes: operations.filter_map do |operation|
+                operation.consumes(self)
+              end.uniq.sort.presence,
+              produces: operations.flat_map do |operation|
+                operation.produces(self)
+              end.uniq.sort.presence,
+              paths: openapi_paths,
+              definitions: openapi_objects[:schemas],
+              parameters: openapi_objects[:parameters],
+              responses: openapi_objects[:responses],
+              securityDefinitions: openapi_objects[:security_schemes]
+            }
+          else
+            {
+              # Order according to the OpenAPI specification 3.x
+              openapi: version.minor.zero? ? '3.0.3' : '3.1.0',
+              info: openapi_objects[:info],
+              servers: openapi_objects[:servers] ||
+                [default_server&.to_openapi].compact.presence,
+              paths: openapi_paths,
+              components: {
+                schemas: openapi_objects[:schemas],
+                responses: openapi_objects[:responses],
+                parameters: openapi_objects[:parameters],
+                examples: openapi_objects[:examples],
+                requestBodies: openapi_objects[:request_bodies],
+                headers: openapi_objects[:headers],
+                securitySchemes: openapi_objects[:security_schemes],
+                links: openapi_objects[:links],
+                callbacks: openapi_objects[:callbacks]
+              }.compact.presence
+            }
+          end.merge(
+            security: openapi_objects[:security_requirements],
+            tags: openapi_objects[:tags],
+            externalDocs: openapi_objects[:external_docs]
+          ).compact
+        )
       end
 
       # Returns the first RescueHandler to handle +exception+, or nil if no one could be found.
       def rescue_handler_for(exception)
-        components[:rescue_handlers].find { |r| r.match?(exception) }
+        objects[:rescue_handlers].find { |r| r.match?(exception) }
       end
 
       protected
 
-      def attribute_changed(name) # :nodoc:
-        return if name == :openapi
+      # The +Definitions+ instances that directly inherit from this instance.
+      attr_reader :children
 
-        if name == :included_definitions
-          invalidate_ancestors
-        else
-          invalidate_components
-        end
+      # The +Definitions+ instances that directly include this instance.
+      attr_reader :dependent_definitions
+
+      # The +Definitions+ instances included.
+      attr_reader :included_definitions
+
+      def attribute_changed(*) # :nodoc:
+        invalidate_objects
       end
 
       # Invoked whenever it is included in another +Definitions+ instance.
@@ -259,43 +335,73 @@ module Jsapi
       # Invalidates cached ancestors.
       def invalidate_ancestors
         @ancestors = nil
-        @components = nil
-        (children + dependent_definitions).each(&:invalidate_ancestors)
+        @objects = nil
+        @children&.each(&:invalidate_ancestors)
+        @dependent_definitions&.each(&:invalidate_ancestors)
       end
 
-      # Invalidates cached components.
-      def invalidate_components
-        @components = nil
-        (children + dependent_definitions).each(&:invalidate_components)
+      # Invalidates cached objects.
+      def invalidate_objects
+        @objects = nil
+        @children&.each(&:invalidate_objects)
+        @dependent_definitions&.each(&:invalidate_objects)
       end
 
       private
 
       def circular_dependency?(other)
         return true if other == self
-        return false if other.included_definitions.none?
+        return false unless other.included_definitions&.any?
 
         other.included_definitions.any? { |included| circular_dependency?(included) }
       end
 
-      def components
-        @components ||= ancestors.each_with_object({}) do |ancestor, components|
-          %i[defaults operations parameters request_bodies responses schemas].each do |type|
-            (components[type] ||= {}).reverse_merge!(ancestor.send(type))
+      def default_operation_name
+        @default_operation_name ||=
+          if (name = @owner.try(:name))
+            name.demodulize.delete_suffix('Controller').underscore
           end
-          %i[on_rescues rescue_handlers].each do |type|
-            (components[type] ||= []).push(*ancestor.send(type))
+      end
+
+      def default_operation_path
+        @default_operation_path ||= "/#{default_operation_name}"
+      end
+
+      def default_server
+        @default_server ||=
+          if (name = @owner.try(:name))
+            Server.new(
+              url: name.deconstantize.split('::')
+                       .map(&:underscore)
+                       .join('/').prepend('/')
+            )
           end
-        end
       end
 
-      def default_operation_name
-        @default_operation_name ||=
-          @owner.to_s.demodulize.delete_suffix('Controller').underscore
+      def objects
+        @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)
+            else
+              objects[key] ||= value
+            end
+          end
+        end
       end
 
-      def default_path
-        @default_path ||= "/#{default_operation_name}"
+      def object_to_openapi(object, version)
+        case object
+        when Array
+          object.map { |item| object_to_openapi(item, version) }
+        when Hash
+          object.transform_values { |value| object_to_openapi(value, version) }
+        else
+          object.respond_to?(:to_openapi) ? object.to_openapi(version, self) : object
+        end
       end
     end
   end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Example
+      # Specifies an example object.
+      class Model < Base::Model
+        include OpenAPI::Extensions
+
+        ##
+        # :attr: description
+        # The 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 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

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+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
+    end
+  end
+end

data/lib/jsapi/meta/example.rb

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

data/lib/jsapi/meta/external_documentation.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Specifies an external documentation object.
+    class ExternalDocumentation < Base::Model
+      include OpenAPI::Extensions
+
+      ##
+      # :attr: description
+      # The description of the external documentation.
+      attribute :description, String
+
+      ##
+      # :attr: url
+      # The URL of the external documentation.
+      attribute :url, String
+
+      # Returns a hash representing the \OpenAPI external documentation object.
+      def to_openapi(*)
+        with_openapi_extensions(url: url, description: description)
+      end
+    end
+  end
+end