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

data/lib/praxis.rb

@@ -50,7 +50,7 @@ module Praxis
   autoload :RestfulDocGenerator, 'praxis/restful_doc_generator'
   module Docs
     autoload :Generator, 'praxis/docs/generator'
-    autoload :LinkBuilder, 'praxis/docs/link_builder'
+    autoload :OpenApiGenerator, 'praxis/docs/open_api_generator'
   end
 
   # types
@@ -60,7 +60,6 @@ module Praxis
     autoload :MultipartArray, 'praxis/types/multipart_array'
   end
 
-  autoload :Links, 'praxis/links'
   autoload :MediaType, 'praxis/media_type'
   autoload :MediaTypeIdentifier, 'praxis/media_type_identifier'
   autoload :Multipart, 'praxis/types/multipart'
@@ -88,15 +87,19 @@ module Praxis
     autoload :MapperSelectors, 'praxis/extensions/mapper_selectors'
     autoload :Rendering, 'praxis/extensions/rendering'
     autoload :FieldExpansion, 'praxis/extensions/field_expansion'
+    autoload :AttributeFiltering, 'praxis/extensions/attribute_filtering'
     autoload :ActiveRecordFilterQueryBuilder, 'praxis/extensions/attribute_filtering/active_record_filter_query_builder'
     autoload :SequelFilterQueryBuilder, 'praxis/extensions/attribute_filtering/sequel_filter_query_builder'
+    autoload :Pagination, 'praxis/extensions/pagination'
+    module Pagination
+      autoload :ActiveRecordPaginationHandler, 'praxis/extensions/pagination/active_record_pagination_handler'
+      autoload :SequelPaginationHandler, 'praxis/extensions/pagination/sequel_pagination_handler'
+    end
   end
 
   module Handlers
     autoload :Plain, 'praxis/handlers/plain'
     autoload :JSON, 'praxis/handlers/json'
-    autoload :WWWForm, 'praxis/handlers/www_form'
-    autoload :XML, 'praxis/handlers/xml'
   end
 
   module BootloaderStages

data/lib/praxis/action_definition.rb

@@ -12,9 +12,8 @@ module Praxis
 
     attr_reader :name
     attr_reader :resource_definition
-    attr_reader :routes
-    attr_reader :primary_route
-    attr_reader :named_routes
+    attr_reader :api_definition
+    attr_reader :route
     attr_reader :responses
     attr_reader :traits
 
@@ -37,7 +36,7 @@ module Praxis
       @resource_definition = resource_definition
       @responses = Hash.new
       @metadata = Hash.new
-      @routes = []
+      @route = nil
       @traits = []
 
       if (media_type = resource_definition.media_type)
@@ -179,12 +178,7 @@ module Praxis
     def routing(&block)
       @routing_config.instance_eval &block
 
-      @routes = @routing_config.routes
-      @primary_route = @routing_config.routes.first
-      @named_routes = @routing_config.routes.each_with_object({}) do |route, hash|
-        next if route.name.nil?
-        hash[route.name] = route
-      end
+      @route = @routing_config.route
     end
 
 
@@ -232,9 +226,8 @@ module Praxis
         end
         hash[:traits] = traits if traits.any?
         # FIXME: change to :routes along with api browser
-        hash[:urls] = routes.collect do |route|
-          ActionDefinition.url_description(route: route, params: self.params, params_example: params_example)
-        end.compact
+        # FIXME: change urls to url ... (along with the browser)
+        hash[:urls] = [ ActionDefinition.url_description(route: route, params: self.params, params_example: params_example) ]
         self.class.doc_decorations.each do |callback|
           callback.call(self, hash)
         end
@@ -252,10 +245,10 @@ module Praxis
 
     def params_description(example:)
       route_params = []
-      if primary_route.nil?
-        warn "Warning: No routes defined for #{resource_definition.name}##{name}."
+      if route.nil?
+        warn "Warning: No route defined for #{resource_definition.name}##{name}."
       else
-        route_params = primary_route.path.
+        route_params = route.path.
           named_captures.
           keys.
           collect(&:to_sym)

data/lib/praxis/api_general_info.rb

@@ -15,6 +15,19 @@ module Praxis
       end
     end
 
+    # Allow any custom method to get/set any value
+    def method_missing(name, val=nil)
+      if val.nil?
+        get(name)
+      else
+        set(name, val)
+      end
+    end
+
+    def respond_to_missing?(*)
+      true
+    end
+
     def get(k)
       return @data[k] if @data.key?(k)
       return @global_info.get(k) if @global_info
@@ -41,6 +54,14 @@ module Praxis
       end
     end
 
+    def logo_url(val=nil)
+      if val.nil?
+        get(:logo_url)
+      else
+        set(:logo_url, val)
+      end
+    end
+
     def description(val=nil)
       if val.nil?
         get(:description)

data/lib/praxis/application.rb

@@ -61,8 +61,7 @@ module Praxis
 
       builtin_handlers = {
         'plain' => Praxis::Handlers::Plain,
-        'json' => Praxis::Handlers::JSON,
-        'x-www-form-urlencoded' => Praxis::Handlers::WWWForm
+        'json' => Praxis::Handlers::JSON
       }
       # Register built-in handlers unless the app already provided its own
       builtin_handlers.each_pair do |name, handler|

data/lib/praxis/bootloader_stages/routing.rb

@@ -23,10 +23,8 @@ module Praxis
       def execute
         application.controllers.each do |controller|
           controller.definition.actions.each do |action_name, action|
-            action.routes.each do |route|
-              target = target_factory(controller, action_name)
-              application.router.add_route target, route
-            end
+            target = target_factory(controller, action_name)
+            application.router.add_route target, action.route
           end
         end
       end

data/lib/praxis/docs/generator.rb

@@ -120,12 +120,7 @@ module Praxis
         File.open(filename, 'w') {|f| f.write(JSON.pretty_generate(data))}
       end
 
-      def write_version_file( version )
-        version_info = infos_by_version[version]
-        # Hack, let's "inherit/copy" all traits of a version from the global definition
-        # Eventually traits should be defined for a version (and inheritable from global) so we'll emulate that here
-        version_info[:traits] = infos_by_version[:traits]
-        dumped_resources = dump_resources( resources_by_version[version] )
+      def scan_types_for_version(version, dumped_resources)
         found_media_types =  resources_by_version[version].select{|r| r.media_type}.collect {|r| r.media_type.describe }
 
         # We'll start by processing the rendered mediatypes
@@ -150,7 +145,17 @@ module Praxis
           processed_types += newfound
           newfound = scan_dump_for_types( dumped, processed_types )
         end
+        processed_types
+      end
 
+      def write_version_file( version )
+        version_info = infos_by_version[version]
+        # Hack, let's "inherit/copy" all traits of a version from the global definition
+        # Eventually traits should be defined for a version (and inheritable from global) so we'll emulate that here
+        version_info[:traits] = infos_by_version[:traits]
+
+        dumped_resources = dump_resources( resources_by_version[version] )
+        processed_types = scan_types_for_version(version, dumped_resources)
         dumped_schemas = dump_schemas( processed_types )
         full_data = {
           info: version_info[:info],

data/lib/praxis/docs/open_api_generator.rb

@@ -0,0 +1,255 @@
+require_relative 'openapi/info_object.rb'
+require_relative 'openapi/server_object.rb'
+require_relative 'openapi/paths_object.rb'
+require_relative 'openapi/tag_object.rb'
+
+module Praxis
+  module Docs
+
+    class OpenApiGenerator < Generator
+      API_DOCS_DIRNAME = 'docs/openapi' 
+
+      # substitutes ":params_like_so" for {params_like_so}
+      def self.templatize_url( string )
+        Mustermann.new(string).to_templates.first
+      end
+
+      def save!
+        initialize_directories
+        # Restrict the versions listed in the index file to the ones for which we have at least 1 resource
+        write_index_file( for_versions: resources_by_version.keys )
+        resources_by_version.keys.each do |version|
+          write_version_file(version)
+        end
+      end
+
+      def initialize(root)
+        require 'yaml'
+        @root = root
+        @resources_by_version =  Hash.new do |h,k|
+          h[k] = Set.new
+        end
+
+        @infos = ApiDefinition.instance.infos
+        collect_resources
+        collect_types
+      end
+
+      private
+
+      def write_index_file( for_versions: )
+        # TODO. create a simple html file that can link to the individual versions available
+      end
+
+      def write_version_file( version )
+        # version_info = infos_by_version[version]
+        # # Hack, let's "inherit/copy" all traits of a version from the global definition
+        # # Eventually traits should be defined for a version (and inheritable from global) so we'll emulate that here
+        # version_info[:traits] = infos_by_version[:traits]
+        dumped_resources = dump_resources( resources_by_version[version] )
+        processed_types = scan_types_for_version(version, dumped_resources)
+
+        # Here we have:
+        # processed types: which includes mediatypes and normal types...real classes
+        # processed resources for this version: resources_by_version[version]
+
+        info_object = OpenApi::InfoObject.new(version: version, api_definition_info: @infos[version])
+        # We only support a server in Praxis ... so we'll use the base path
+        server_object = OpenApi::ServerObject.new( url: @infos[version].base_path )
+        
+        paths_object = OpenApi::PathsObject.new( resources: resources_by_version[version])
+
+        full_data = {
+          openapi: "3.0.2",
+          info: info_object.dump,
+          servers: [server_object.dump],
+          paths: paths_object.dump,
+          # responses: {}, #TODO!! what do we get here? the templates?...need to transform to "Responses Definitions Object"
+          # securityDefinitions: {}, # NOTE: No security definitions in Praxis
+          # security: [], # NOTE: No security definitions in Praxis
+        }
+
+        # Create the top level tags by:
+        # 1- First adding all the resource display names (and descriptions)
+        tags_for_resources = resources_by_version[version].collect do |resource|
+          OpenApi::TagObject.new(name: resource.display_name, description: resource.description ).dump
+        end
+        full_data[:tags] = tags_for_resources
+        # 2- Then adding all of the top level traits but marking them special with the x-traitTag (of Redoc)
+        tags_for_traits = (ApiDefinition.instance.traits).collect do |name, info|
+          OpenApi::TagObject.new(name: name, description: info.description).dump.merge(:'x-traitTag' => true)
+        end
+        unless tags_for_traits.empty?
+          full_data[:tags] = full_data[:tags] + tags_for_traits
+        end
+
+        # Include only MTs (i.e., not custom types or simple types...)
+        component_schemas = reusable_schema_objects(processed_types.select{|t| t < Praxis::MediaType})
+        
+        # 3- Then adding all of the top level Mediatypes...so we can present them at the bottom, otherwise they don't show
+        tags_for_mts = component_schemas.map do |(name, info)|
+          special_redoc_anchor = "<SchemaDefinition schemaRef=\"#/components/schemas/#{name}\" showReadOnly={true} showWriteOnly={true} />"
+          guessed_display = name.split('-').last # TODO!!!the informational hash does not seem to come with the "description" value set...hmm
+          OpenApi::TagObject.new(name: name, description: special_redoc_anchor).dump.merge(:'x-displayName' => guessed_display)
+        end
+        unless tags_for_mts.empty?
+          full_data[:tags] = full_data[:tags] + tags_for_mts
+        end
+
+        # Include all the reusable schemas in the components hash
+        full_data[:components] = {
+          schemas: component_schemas
+        }
+
+        # REDOC specific grouping of sidebar
+        resource_tags = { name: 'Resources', tags: tags_for_resources.map{|t| t[:name]} }
+        schema_tags = { name: 'Models', tags: tags_for_mts.map{|t| t[:name]} }
+        full_data['x-tagGroups'] = [resource_tags, schema_tags]
+
+        # if parameter_object = convert_to_parameter_object( version_info[:info][:base_params] )
+        #   full_data[:parameters] = parameter_object
+        # end
+        #puts JSON.pretty_generate( full_data )
+        # Write the file
+        version_file = ( version == "n/a" ? "unversioned" : version )
+        filename = File.join(doc_root_dir, version_file, 'openapi')
+
+        puts "Generating Open API file : #{filename} (json and yml) "
+        json_data = JSON.pretty_generate(full_data)
+        File.open(filename+".json", 'w') {|f| f.write(json_data)}
+        converted_full_data = JSON.parse( json_data ) # So symbols disappear
+        File.open(filename+".yml", 'w') {|f| f.write(YAML.dump(converted_full_data))}
+
+        html =<<-EOB
+          <!DOCTYPE html>
+          <html>
+            <head>
+              <title>ReDoc</title>
+              <!-- needed for adaptive design -->
+              <meta charset="utf-8"/>
+              <meta name="viewport" content="width=device-width, initial-scale=1">
+              <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+          
+              <!--
+              ReDoc doesn't change outer page styles
+              -->
+              <style>
+                body {
+                  margin: 0;
+                  padding: 0;
+                }
+              </style>
+            </head>
+            <body>
+              <redoc spec-url='http://localhost:9090/#{version_file}/openapi.json'></redoc>
+              <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
+            </body>
+          </html>
+        EOB
+        html_file = File.join(doc_root_dir, version_file, 'index.html')
+        File.write(html_file, html)
+      end
+
+      def initialize_directories
+        @doc_root_dir = File.join(@root, API_DOCS_DIRNAME)
+
+        # remove previous data (and reset the directory)
+        FileUtils.rm_rf @doc_root_dir if File.exists?(@doc_root_dir)
+        FileUtils.mkdir_p @doc_root_dir unless File.exists? @doc_root_dir
+        resources_by_version.keys.each do |version|
+          FileUtils.mkdir_p @doc_root_dir + '/' + version
+        end
+        FileUtils.mkdir_p @doc_root_dir + '/unversioned'
+      end
+
+      def normalize_media_types( mtis )
+        mtis.collect do |mti|
+           MediaTypeIdentifier.load(mti).to_s
+         end
+      end
+
+      def reusable_schema_objects(types)
+        types.each_with_object({}) do |(type), accum|
+          the_type = \
+            if type.respond_to? :as_json_schema
+              type
+            else # If it is a blueprint ... for now, it'd be through the attribute
+              type.attribute
+            end
+          accum[type.id] = the_type.as_json_schema(shallow: false)
+        end
+      end
+
+      def convert_to_parameter_object( params )
+        # TODO!! actually convert each of them
+        puts "TODO! convert to parameter object"
+        params
+      end
+
+      def convert_traits_to_tags( traits )
+        traits.collect do |name, info|
+          { name: name, description: info[:description] }
+        end
+      end
+
+
+      def dump_responses_object( responses )
+        responses.each_with_object({}) do |(name, info), hash|
+          data = { description: info[:description] || "" }
+          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
+
+#          data[:schema] = ???TODO!!
+          if headers_object = dump_response_headers_object( info[:headers] )
+            data[:headers] = headers_object
+          end
+          if info[:payload] && ( examples_object = dump_response_examples_object( info[:payload][:examples] ) )
+            data[:examples] = examples_object
+          end
+          hash[info[:status]] = data
+        end
+      end
+      # def dump_response_headers_object( headers )
+      #   puts "WARNING!! Finish this. It seems that headers for responses are never set in the hash??"
+      #   unless headers.empty?
+      #     binding.pry
+      #     puts headers
+      #   end
+      # end
+
+      def dump_response_examples_object( examples )
+        examples.each_with_object({}) do |(name, info), hash|
+          hash[info[:content_type]] = info[:body]
+        end
+      end
+
+
+      def dump_resources( resources )
+        resources.each_with_object({}) do |r, hash|
+          # Do not report undocumentable resources
+          next if r.metadata[:doc_visibility] == :none
+          context = [r.id]
+          resource_description = r.describe(context: context)
+
+          # strip actions with doc_visibility of :none
+          resource_description[:actions].reject! { |a| a[:metadata][:doc_visibility] == :none }
+
+          # Go through the params/payload of each action and augment them by
+          # adding a generated example (then stick it into the description hash)
+          r.actions.each do |action_name, action|
+            # skip actions with doc_visibility of :none
+            next if action.metadata[:doc_visibility] == :none
+
+            action_description = resource_description[:actions].find {|a| a[:name] == action_name }
+          end
+
+          hash[r.id] = resource_description
+        end
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+module Praxis
+  module Docs
+    module OpenApi
+      class InfoObject
+        attr_reader :info, :version
+        def initialize(version: , api_definition_info: )
+          @version = version
+          @info = api_definition_info
+          raise "OpenApi docs require a 'Title' for your API." unless info.title
+        end
+
+        def dump
+          data ={
+            title: info.title,
+            description: info.description,
+            termsOfService: info.termsOfService,
+            contact: info.contact,
+            license: info.license,
+            version: version,
+            :'x-name' => info.name,
+            :'x-logo' => {
+              url: info.logo_url,
+              backgroundColor: "#FFFFFF",
+              altText: info.title
+            }
+          }
+        end
+      end
+    end
+  end
+end