praxis 2.0.pre.3 → 2.0.pre.8

data/lib/praxis/docs/openapi/media_type_object.rb

@@ -0,0 +1,59 @@
+module Praxis
+  module Docs
+    module OpenApi
+      class MediaTypeObject
+        attr_reader :schema, :example
+        def initialize(schema:, example:)
+          @schema = schema
+          @example = example
+        end
+
+        def dump
+          {
+           schema: schema,
+           example: example,   
+           # encoding: TODO SUPPORT IT maybe be great/necessary for multipart
+          }
+        end
+
+        # Helper to create the typical content attribute for responses and request bodies
+        def self.create_content_attribute_helper(type: , example_payload:, example_handlers: nil)
+          # Will produce 1 example encoded with a given handler (and marking it with the given content type)
+          unless example_handlers
+            example_handlers = [ {'application/json' => 'json' } ] 
+          end
+          # NOTE2: we should just create a $ref here unless it's an anon mediatype...
+          return {} if type.is_a? SimpleMediaType           # NOTE: skip if it's a SimpleMediaType?? ... is that correct?
+
+          the_schema = if type.anonymous? || ! (type < Praxis::MediaType) # Avoid referencing  custom/simple Types? (i.e., just MTs)
+            SchemaObject.new(info: type).dump_schema
+          else
+            { '$ref': "#/components/schemas/#{type.id}" }
+          end
+
+          if example_payload
+            examples_by_content_type = {}
+            rendered_payload = example_payload.dump
+
+            example_handlers.each do |spec|
+              content_type, handler_name = spec.first
+              handler = Praxis::Application.instance.handlers[handler_name]
+              # ReDoc is not happy to display json generated outputs when served as JSON...wtf?
+              generated = handler.generate(rendered_payload)
+              final = ( handler_name == 'json') ? JSON.parse(generated) : generated
+              examples_by_content_type[content_type] = final
+            end
+          end
+
+          # Key string (of MT) , value MTObject
+          content_hash = examples_by_content_type.each_with_object({}) do |(content_type, example_hash),accum|
+            accum[content_type] = MediaTypeObject.new(
+              schema: the_schema, # Every MT will have the same exact type..oh well .. maybe a REF?
+              example: example_hash,
+            ).dump
+          end
+        end
+      end
+    end
+  end
+end

data/lib/praxis/docs/openapi/operation_object.rb

@@ -0,0 +1,40 @@
+require_relative 'parameter_object'
+require_relative 'request_body_object'
+require_relative 'responses_object'
+
+module Praxis
+  module Docs
+    module OpenApi
+      class OperationObject
+        # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operation-object
+        attr_reader :id, :url, :action, :tags
+        def initialize(id:, url:, action:, tags:)
+          @id = id
+          @url = url
+          @action = action
+          @tags = tags
+        end
+
+        def dump
+          all_parameters = ParameterObject.process_parameters(action)
+          all_tags = tags + action.traits
+          h = {
+            summary: action.name.to_s,
+            description: action.description,
+            #externalDocs: {}, # TODO/FIXME
+            operationId: id,
+            responses: ResponsesObject.new(responses: action.responses).dump, 
+            # callbacks
+            # deprecated: false
+            # security: [{}]
+            # servers: [{}]
+          }
+          h[:tags] = all_tags.uniq unless all_tags.empty?
+          h[:parameters] = all_parameters unless all_parameters.empty?
+          h[:requestBody] = RequestBodyObject.new(attribute: action.payload ).dump if action.payload
+          h
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+require_relative 'schema_object'
+
+module Praxis
+  module Docs
+    module OpenApi
+      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:)
+          @location = location
+          @name = name
+          @info = info
+          @is_required = is_required
+        end
+
+        def dump
+          # Fixed fields
+          h = { name: name, in: location }
+          h[:description] = info.options[:description] if info.options[:description]
+          h[:required] = is_required if is_required
+          # h[:deprecated] = false
+          # h[:allowEmptyValue] ??? TODO: support in Praxis
+
+          # Other supported attributes
+          # 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
+          h[:example] = schema.dump_example
+          h
+        end
+
+        def self.process_parameters( action )
+          output = []
+          # 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
+            end
+          end
+  
+          if action.params
+            route_params = \
+              unless action.route
+                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|
+              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
+            end
+          end
+
+          output
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+require_relative 'operation_object.rb'
+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
+          # where the subhash has verb keys and path_items as values
+          # {
+          #   "/pets": {
+          #       "get": {...},
+          #       "post": { ...}
+          #   "/humans": {
+          #       "get": {...},
+          @paths = Hash.new {|h,k| h[k] = {} }
+        end
+
+
+        def dump
+          resources.each do |resource|
+            compute_resource_paths( resource )
+          end
+          paths
+        end
+
+        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|
+            params_example =  action.params ? action.params.example(nil) : nil
+            url = ActionDefinition.url_description(route: action.route, params: action.params, params_example: params_example)
+
+            verb = url[:verb].downcase
+            templetized_path = OpenApiGenerator.templatize_url(url[:path])
+            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
+          end
+          # For each path, we can further annotate with 
+          # servers
+          # parameters 
+          # But we don't have that concept in praxis
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+require_relative 'schema_object'
+
+module Praxis
+  module Docs
+    module OpenApi
+      class RequestBodyObject
+        # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#request-body-object
+        attr_reader :attribute 
+        def initialize(attribute:)
+          @attribute = attribute
+        end
+
+        def dump
+          h = {}
+          h[:description] = attribute.options[:description] if attribute.options[:description]
+          h[:required] = attribute.options[:required] || false
+
+          # 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
+
+          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), 
+                                                                        example_handlers: example_handlers)
+          # # Key string (of MT) , value MTObject
+          # content_hash = info[:examples].each_with_object({}) do |(handler, example_hash),accum|
+          #   content_type = example_hash[:content_type]
+          #   accum[content_type] = MediaTypeObject.new(
+          #     schema: dumped_schema, # Every MT will have the same exact type..oh well
+          #     example: info[:examples][handler][:body],
+          #   ).dump
+          # end
+          # # TODO! Handle Multipart types! they look like arrays now in the schema...etc
+          # h[:content] = content_hash
+          h
+        end
+
+        
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+require_relative 'media_type_object'
+
+module Praxis
+  module Docs
+    module OpenApi
+      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|
+            default_handlers.include?(k)
+          end
+        end
+
+        def dump_response_headers_object( headers )
+          headers.each_with_object({}) do |(name,data),accum|
+            # data is a hash with :value and :type keys
+            # How did we say in that must match a value in json schema again??
+            accum[name] = {
+              schema: SchemaObject.new(info: data[:type])
+              # allowed values:  [ data[:value] ] ??? is this the right json schema way?
+            }
+          end
+        end
+
+        def dump
+          data = { 
+            description: info.description || ''
+          }
+          if headers_object = dump_response_headers_object( info.headers )
+            data[:headers] = headers_object
+          end
+
+          if info.media_type
+
+            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})
+            end
+            data[:content] = MediaTypeObject.create_content_attribute_helper(
+                                                                            type: info.media_type, 
+                                                                            example_payload: info.example(nil),
+                                                                            example_handlers: example_handlers)
+          end
+
+          # if payload = info[:payload]
+          #   body_type= payload[:id]
+          #   raise "WAIT! response payload doesn't have an existing id for the schema!!! (do an if, and describe it if so)" unless body_type
+          #   data[:schema] = {"$ref" => "#/definitions/#{body_type}" }
+          # end
+
+          
+          # TODO: we do not support 'links'
+          data
+        end
+
+        
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+require_relative 'response_object'
+
+module Praxis
+  module Docs
+    module OpenApi
+      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": {
+          #     "description": "a pet to be returned",
+          #     "content": {
+          #       "application/json": {
+          #         "schema": {
+          #           type: :object
+          #         }
+          #       }
+          #     }
+          #   },
+          #   "default": {
+          #     "description": "Unexpected error",
+          #     "content": {
+          #       "application/json": {
+          #         "schema": {
+          #           type: :object
+          #         }
+          #       }
+          #     }
+          #   }
+          # }
+          responses.each_with_object({}) do |(_response_name, response_definition), hash|
+            hash[response_definition.status.to_s] = ResponseObject.new(info: response_definition).dump
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+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
+        def initialize(info:)
+          #info could be an attribute ... or a type?
+          if info.is_a? Attributor::Attribute
+            @attribute = info
+          else
+            @type = info
+          end
+        end
+
+        def dump_example
+          ex = \
+            if attribute
+              attribute.example
+            else
+              type.example
+            end
+          ex.respond_to?(:dump) ? ex.dump : ex
+        end
+
+        def dump_schema
+          if attribute
+            attribute.as_json_schema(shallow: true, example: nil)
+          else
+            type.as_json_schema(shallow: true, example: nil)
+          end
+          # # TODO: FIXME: return a generic object type if the passed info was weird. 
+          # return { type: :object } unless info
+
+          # h = {
+          #   #type: convert_family_to_json_type( info[:type] )
+          #   type: info[:type]
+          #   #TODO: format?
+          # }
+          # # required prop!!!??
+          # 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]
+          #   unless member_type
+          #     member_type = { family: :hash}
+          #   end
+          #   h[:items] = SchemaObject.new(info: member_type ).dump_schema
+          # end
+          # h
+        rescue => e
+          puts "Error dumping schema #{e}"
+        end
+        
+        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!
+            :array
+          when :numeric
+            case praxis_type[:id]
+            when 'Attributor-Integer'
+              :integer
+            when 'Attributor-BigDecimal'
+              :integer
+            when 'Attributor-Float'
+              :number
+            end
+          when :temporal
+            :string
+          when :boolean
+            :boolean
+          else
+            raise "Unknown praxis family type: #{praxis_type[:family]}"
+          end
+        end
+
+      end
+    end
+  end
+end