praxis 2.0.pre.17 → 2.0.pre.21

data/lib/praxis/docs/open_api/parameter_object.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'schema_object'
 
 module Praxis
@@ -6,7 +8,8 @@ module Praxis
       class ParameterObject
         # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameter-object
         attr_reader :location, :name, :is_required, :info
-        def initialize(location: , name:, is_required:,  info:)
+
+        def initialize(location:, name:, is_required:, info:)
           @location = location
           @name = name
           @info = info
@@ -25,39 +28,39 @@ module Praxis
           # style
           # explode
           # allowReserved
-          
+
           # Now merge the rest schema and example
           # schema
           # example
           # examples (Example and Examples are mutually exclusive)
           schema = SchemaObject.new(info: info)
           h[:schema] = schema.dump_schema
-          # Note: we do not support the 'content' key...we always use schema
+          # NOTE: we do not support the 'content' key...we always use schema
           h[:example] = schema.dump_example
           h
         end
 
-        def self.process_parameters( action )
+        def self.process_parameters(action)
           output = []
-          # An array, with one hash per param inside  
+          # An array, with one hash per param inside
           if action.headers
-            (action.headers.attributes||{}).each_with_object(output) do |(name, info), out|
-              out << ParameterObject.new( location: 'header', name: name, is_required: info.options[:required], info: info ).dump
+            (action.headers.attributes || {}).each_with_object(output) do |(name, info), out|
+              out << ParameterObject.new(location: 'header', name: name, is_required: info.options[:required], info: info).dump
             end
           end
-  
+
           if action.params
             route_params = \
-              unless action.route
+              if action.route
+                action.route.path.named_captures.keys.collect(&:to_sym)
+              else
                 warn "Warning: No routes defined for action #{action.name}"
                 []
-              else
-                action.route.path.named_captures.keys.collect(&:to_sym)
               end
-            (action.params.attributes||{}).each_with_object(output) do |(name, info), out|
+            (action.params.attributes || {}).each_with_object(output) do |(name, info), out|
               in_type = route_params.include?(name) ? :path : :query
-              is_required = (in_type == :path ) ? true : info.options[:required]
-              out << ParameterObject.new( location: in_type, name: name, is_required: is_required, info: info ).dump
+              is_required = in_type == :path ? true : info.options[:required]
+              out << ParameterObject.new(location: in_type, name: name, is_required: is_required, info: info).dump
             end
           end
 

data/lib/praxis/docs/open_api/paths_object.rb

@@ -1,10 +1,13 @@
-require_relative 'operation_object.rb'
+# frozen_string_literal: true
+
+require_relative 'operation_object'
 module Praxis
   module Docs
     module OpenApi
       class PathsObject
         # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#paths-object
         attr_reader :resources, :paths
+
         def initialize(resources:)
           @resources = resources
           # A hash with keys of paths, and values of hash
@@ -15,18 +18,17 @@ module Praxis
           #       "post": { ...}
           #   "/humans": {
           #       "get": {...},
-          @paths = Hash.new {|h,k| h[k] = {} }
+          @paths = Hash.new { |h, k| h[k] = {} }
         end
 
-
         def dump
           resources.each do |resource|
-            compute_resource_paths( resource )
+            compute_resource_paths(resource)
           end
           paths
         end
 
-        def compute_resource_paths( resource )
+        def compute_resource_paths(resource)
           id = resource.id
           # fill in the paths hash with a key for each path for each action/route
           resource.actions.each do |action_name, action|
@@ -38,15 +40,15 @@ module Praxis
             path_entry = paths[templetized_path]
             # Let's fill in verb stuff within the working hash
             raise "VERB #{_verb} already defined for #{id}!?!?!" if path_entry[verb]
-            
+
             action_uid = "action-#{action_name}-#{id}"
             # Add a tag matching the resource name (hoping all actions of a resource are grouped)
             action_tags = [resource.display_name]
-            path_entry[verb] = OperationObject.new( id: action_uid, url: url, action: action, tags: action_tags).dump
+            path_entry[verb] = OperationObject.new(id: action_uid, url: url, action: action, tags: action_tags).dump
           end
-          # For each path, we can further annotate with 
+          # For each path, we can further annotate with
           # servers
-          # parameters 
+          # parameters
           # But we don't have that concept in praxis
         end
       end

data/lib/praxis/docs/open_api/request_body_object.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'schema_object'
 
 module Praxis
@@ -5,7 +7,8 @@ module Praxis
     module OpenApi
       class RequestBodyObject
         # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#request-body-object
-        attr_reader :attribute 
+        attr_reader :attribute
+
         def initialize(attribute:)
           @attribute = attribute
         end
@@ -18,18 +21,18 @@ module Praxis
           # OpenApi wants a set of bodies per MediaType/Content-Type
           # For us there's really only one schema (regardless of encoding)...
           # so we'll show all the supported MTs...but repeating the schema
-          #dumped_schema = SchemaObject.new(info: attribute).dump_schema
+          # dumped_schema = SchemaObject.new(info: attribute).dump_schema
 
           example_handlers = if attribute.type < Praxis::Types::MultipartArray
-            ident = MediaTypeIdentifier.load('multipart/form-data')
-            [{ident.to_s => 'plain'}] # Multipart content type, but with the plain renderer (so there's no modification)
-          else
-            # TODO: We could run it through other handlers I guess...if they're registered
-            [{'application/json' => 'json'}]
-          end
-          
-          h[:content] = MediaTypeObject.create_content_attribute_helper(type: attribute.type, 
-                                                                        example_payload: attribute.example(nil), 
+                               ident = MediaTypeIdentifier.load('multipart/form-data')
+                               [{ ident.to_s => 'plain' }] # Multipart content type, but with the plain renderer (so there's no modification)
+                             else
+                               # TODO: We could run it through other handlers I guess...if they're registered
+                               [{ 'application/json' => 'json' }]
+                             end
+
+          h[:content] = MediaTypeObject.create_content_attribute_helper(type: attribute.type,
+                                                                        example_payload: attribute.example(nil),
                                                                         example_handlers: example_handlers)
           # # Key string (of MT) , value MTObject
           # content_hash = info[:examples].each_with_object({}) do |(handler, example_hash),accum|
@@ -43,8 +46,6 @@ module Praxis
           # h[:content] = content_hash
           h
         end
-
-        
       end
     end
   end

data/lib/praxis/docs/open_api/response_object.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'media_type_object'
 
 module Praxis
@@ -6,33 +8,39 @@ module Praxis
       class ResponseObject
         # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#response-object
         attr_reader :info
+
         def initialize(info:)
           @info = info
           default_handlers = ApiDefinition.instance.info.produces
-          @output_handlers = Praxis::Application.instance.handlers.select do |k,v|
+          @output_handlers = Praxis::Application.instance.handlers.select do |k, _v|
             default_handlers.include?(k)
           end
         end
 
-        def dump_response_headers_object( headers )
-          headers.each_with_object({}) do |(name,data),accum|
-            # each header comes from Praxis::ResponseDefinition 
+        def dump_response_headers_object(headers)
+          headers.each_with_object({}) do |(name, data), accum|
+            # each header comes from Praxis::ResponseDefinition
             # the keys are the header names, and value can be:
             #  "true"  => means it only needs to exist
             #  String => which means that it has to fully match
             #  Regex  => which means it has to regexp match it
 
             # Get the schema from the type (defaulting to string in case the type doesn't have the as_json_schema defined)
-            schema = data[:attribute].type.as_json_schema rescue { type: :string }
+            schema = begin
+              data[:attribute].type.as_json_schema
+            rescue StandardError
+              { type: :string }
+            end
             hash = { description: data[:description] || '', schema: schema }
-            # Note, our Headers in response definition are not full types...they're basically only 
+            # Note, our Headers in response definition are not full types...they're basically only
             # strings, which can either match anything, match the exact word or match a regex
             # they don't even have a description...
             data_value = data[:value]
-            if data_value.is_a? String
+            case data_value
+            when String
               hash[:pattern] = "^#{data_value}$" # Exact String match
-            elsif data_value.is_a? Regexp
-              sanitized_pattern = data_value.inspect[1..-2] #inspect returns enclosing '/' characters
+            when Regexp
+              sanitized_pattern = data_value.inspect[1..-2] # inspect returns enclosing '/' characters
               hash[:pattern] = sanitized_pattern
             end
 
@@ -41,10 +49,10 @@ module Praxis
         end
 
         def dump
-          data = { 
+          data = {
             description: info.description || ''
           }
-          if headers_object = dump_response_headers_object( info.headers )
+          if (headers_object = dump_response_headers_object(info.headers))
             data[:headers] = headers_object
           end
 
@@ -52,12 +60,13 @@ module Praxis
 
             identifier = MediaTypeIdentifier.load(info.media_type.identifier)
             example_handlers = @output_handlers.each_with_object([]) do |(name, _handler), accum|
-              accum.push({ (identifier + name).to_s => name})
+              accum.push({ (identifier + name).to_s => name })
             end
             data[:content] = MediaTypeObject.create_content_attribute_helper(
-                                                                            type: info.media_type, 
-                                                                            example_payload: info.example(nil),
-                                                                            example_handlers: example_handlers)
+              type: info.media_type,
+              example_payload: info.example(nil),
+              example_handlers: example_handlers
+            )
           end
 
           # if payload = info[:payload]
@@ -66,12 +75,9 @@ module Praxis
           #   data[:schema] = {"$ref" => "#/definitions/#{body_type}" }
           # end
 
-          
           # TODO: we do not support 'links'
           data
         end
-
-        
       end
     end
   end

data/lib/praxis/docs/open_api/responses_object.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'response_object'
 
 module Praxis
@@ -6,11 +8,11 @@ module Praxis
       class ResponsesObject
         # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responses-object
         attr_reader :responses
+
         def initialize(responses:)
           @responses = responses
         end
 
-
         def dump
           # {
           #   "200": {

data/lib/praxis/docs/open_api/schema_object.rb

@@ -1,35 +1,70 @@
+# frozen_string_literal: true
+
 module Praxis
   module Docs
     module OpenApi
       class SchemaObject
         # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schema-object
-        attr_reader :type, :attribute
+        attr_reader :type
+
         def initialize(info:)
-          #info could be an attribute ... or a type?
-          if info.is_a? Attributor::Attribute
-            @attribute = info
+          @attribute_options = {}
+
+          # info could be an attribute ... or a type
+          if info.is_a?(Attributor::Attribute)
+            @type = info.type
+            # Save the options that might be attached to the attribute, to add them to the type schema later
+            @attribute_options = info.options
           else
             @type = info
           end
+
+          # Mediatypes have the description method, lower types don't
+          @attribute_options[:description] = @type.description if @type.respond_to?(:description)
+          @collection = type.respond_to?(:member_type)
         end
 
         def dump_example
-          ex = \
-            if attribute
-              attribute.example
-            else
-              type.example
-            end
+          ex = type.example
           ex.respond_to?(:dump) ? ex.dump : ex
         end
 
-        def dump_schema
-          if attribute
-            attribute.as_json_schema(shallow: true, example: nil)
+        def dump_schema(shallow: false, allow_ref: false)
+          # We will dump schemas for mediatypes by simply creating a reference to the components' section
+          if type < Attributor::Container
+            if (type < Praxis::Blueprint || type < Attributor::Model) && allow_ref && !type.anonymous?
+              # TODO: Do we even need a description?
+              h = @attribute_options[:description] ? { 'description' => @attribute_options[:description] } : {}
+
+              Praxis::Docs::OpenApiGenerator.instance.register_seen_component(type)
+              h.merge!('$ref' => "#/components/schemas/#{type.id}")
+            elsif @collection
+              items = OpenApi::SchemaObject.new(info: type.member_type).dump_schema(allow_ref: allow_ref, shallow: false)
+              h = @attribute_options[:description] ? { 'description' => @attribute_options[:description] } : {}
+              h.merge!(type: 'array', items: items)
+            else # Attributor::Struct, etc
+              props = type.attributes.transform_values do |definition|
+                OpenApi::SchemaObject.new(info: definition).dump_schema(allow_ref: true, shallow: shallow)
+              end
+              h = { type: :object, properties: props } # TODO: Example?
+            end
           else
-            type.as_json_schema(shallow: true, example: nil)
+            # OpenApi::SchemaObject.new(info:target).dump_schema(allow_ref: allow_ref, shallow: shallow)
+            # TODO...we need to make sure we can use refs in the underlying components after the first level...
+            # ... maybe we need to loop over the attributes if it's an object/struct?...
+            h = type.as_json_schema(shallow: shallow, example: nil, attribute_options: @attribute_options)
           end
-          # # TODO: FIXME: return a generic object type if the passed info was weird. 
+
+          # Tag on OpenAPI specific requirements that aren't already added in the underlying JSON schema model
+          # Nullable: (it seems we need to ensure there is a null option to the enum, if there is one)
+          if @attribute_options[:null]
+            h[:nullable] = @attribute_options[:null]
+            h[:enum] = h[:enum] + [nil] if h[:enum] && !h[:enum].include?(nil)
+          end
+
+          h
+
+          # # TODO: FIXME: return a generic object type if the passed info was weird.
           # return { type: :object } unless info
 
           # h = {
@@ -41,7 +76,7 @@ module Praxis
           # h[:default] = info[:default] if info[:default]
           # h[:pattern] = info[:regexp] if info[:regexp]
           # # TODO: there are other possible things we can do..maximum, minimum...etc
-  
+
           # if h[:type] == :array
           #   # FIXME: ... hack it for MultiPart arrays...where there's no member attr
           #   member_type =  info[:type][:member_attribute]
@@ -51,27 +86,25 @@ module Praxis
           #   h[:items] = SchemaObject.new(info: member_type ).dump_schema
           # end
           # h
-        rescue => e
+        rescue StandardError => e
           puts "Error dumping schema #{e}"
         end
-        
-        def convert_family_to_json_type( praxis_type )
+
+        def convert_family_to_json_type(praxis_type)
           case praxis_type[:family].to_sym
           when :string
             :string
           when :hash
             :object
-          when :array #Warning! Multipart types are arrays!
+          when :array # Warning! Multipart types are arrays!
             :array
           when :numeric
-            case praxis_type[:id]
-            when 'Attributor-Integer'
-              :integer
-            when 'Attributor-BigDecimal'
-              :integer
-            when 'Attributor-Float'
-              :number
-            end
+            jtypes = {
+              'Attributor-Integer' => :integer,
+              'Attributor-BigDecimal' => :integer,
+              'Attributor-Float' => :number
+            }
+            jtypes[praxis_type[:id]]
           when :temporal
             :string
           when :boolean
@@ -80,7 +113,6 @@ module Praxis
             raise "Unknown praxis family type: #{praxis_type[:family]}"
           end
         end
-
       end
     end
   end

data/lib/praxis/docs/open_api/server_object.rb

@@ -1,10 +1,13 @@
+# frozen_string_literal: true
+
 module Praxis
   module Docs
     module OpenApi
       class ServerObject
         # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#server-object
         attr_reader :url, :description, :variables
-        def initialize(url: , description: nil, variables: [])
+
+        def initialize(url:, description: nil, variables: [])
           @url = url
           @description = description
           @variables = variables
@@ -12,7 +15,7 @@ module Praxis
         end
 
         def dump
-          result = {url: url}
+          result = { url: url }
           result[:description] = description if description
           result[:variables] = variables unless variables.empty?
 

data/lib/praxis/docs/open_api/tag_object.rb

@@ -1,19 +1,22 @@
+# frozen_string_literal: true
+
 module Praxis
   module Docs
     module OpenApi
       class TagObject
         attr_reader :name, :description
-        def initialize(name:,description: )
+
+        def initialize(name:, description:)
           @name = name
           @description = description
         end
 
         def dump
-          {
-            name: name,
-            description: description,
-            #externalDocs: ???,
-          }
+          h = description ? { description: description } : {}
+          h.merge(
+            name: name
+            # externalDocs: ???,
+          )
         end
       end
     end