praxis 2.0.pre.4 → 2.0.pre.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fa827ff7e042719b8976def88a05ab420fa05eb5
-  data.tar.gz: a3c09e65e43ea6d5ef508ca9be649552b271b305
+  metadata.gz: 05fc37d45d8686251eb9691f05b7c9cdcfb3a8fe
+  data.tar.gz: fd5b9c01c4eab9994319eedf5cae50957b8dce06
 SHA512:
-  metadata.gz: 9055b2bb74579f7b0bfb6b2823df6b03dc863e30945314aa7d2251326ad1e4c7bf9a2213b24251ca8334e3e00bca5371b4fbc7d7199e7829ca4f625c9f1f0a97
-  data.tar.gz: e458dcf8e0d69e5df81ca9a2a1bc62250891ac788f7cfd2dbc9e08a76193bcf797d099799f83cfbdc0c2010e3fe3b23bef917efc036a80f95029f0437904f847
+  metadata.gz: d8c4a7698ce165605a1c3a59c7fd014490b86a2bd4a27b2814e05dd1e9fa87d268a88dbd549239a07707f18b9c0a2fa350f45725686a50ef0777e1a32a11a7dc
+  data.tar.gz: 1a93f51757421d516ee80eb0d38101c6f0eff7d9cd9483ebb4fb44634342edf88e5ff7b16b49676cb696e7653843c1a69b7d505eaa4bde954e0bb7ae60b7f13e

data/CHANGELOG.md

@@ -1,6 +1,10 @@
 # Praxis Changelog
 
-## next
+## 2.0.pre.5
+
+- Added support for OpenAPI 3.x document generation. Consider this in Beta state, although it is fairly close to feature complete.
+
+## 2.0.pre.4
 - Reworked the field selection DB query generation to support full tree of eager loaded dependencies
   - Built support for both ActiveRecord and Sequel gems
   - Selected DB fields will include/map the defined resource properties and will always include any necessary fields on both sides of the joins for the given associations.

data/lib/praxis.rb

@@ -51,6 +51,7 @@ module Praxis
   module Docs
     autoload :Generator, 'praxis/docs/generator'
     autoload :LinkBuilder, 'praxis/docs/link_builder'
+    autoload :OpenApiGenerator, 'praxis/docs/open_api_generator'
   end
 
   # types

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/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

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 = \
+              if action.primary_route.nil?
+                warn "Warning: No routes defined for action #{action.name}"
+                []
+              else
+                action.primary_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,58 @@
+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
+            urls = action.routes.collect do |route|
+              ActionDefinition.url_description(route: route, params: action.params, params_example: params_example)
+            end.compact
+            urls.each do |url|
+              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
+          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

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

@@ -0,0 +1,24 @@
+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: [])
+          @url = url
+          @description = description
+          @variables = variables
+          raise "OpenApi docs require a 'url' for your server object." unless url
+        end
+
+        def dump
+          result = {url: url}
+          result[:description] = description if description
+          result[:variables] = variables unless variables.empty?
+
+          result
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module Praxis
+  module Docs
+    module OpenApi
+      class TagObject
+        attr_reader :name, :description
+        def initialize(name:,description: )
+          @name = name
+          @description = description
+        end
+
+        def dump
+          {
+            name: name,
+            description: description,
+            #externalDocs: ???,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/praxis/extensions/attribute_filtering/filtering_params.rb

@@ -62,6 +62,10 @@ module Praxis
             end
           end
   
+          def json_schema_type
+            :string
+          end
+      
           def add_filter(name, operators:, fuzzy:)
             components = name.to_s.split('.').map(&:to_sym)
             attribute, enclosing_type = find_filter_attribute(components, media_type)

data/lib/praxis/extensions/field_selection/field_selector.rb

@@ -7,6 +7,10 @@ module Praxis
           include Attributor::Type
           include Attributor::Dumpable
 
+          def self.json_schema_type
+            :string
+          end
+      
           def self.native_type
             self
           end

data/lib/praxis/links.rb

@@ -54,6 +54,10 @@ module Praxis
       super(false,**opts) # Links must always describe attributes
     end
 
+    def self.json_schema_type
+      @attribute.type.json_schema_type
+    end
+
     def self._finalize!
       super
       if @attribute

data/lib/praxis/mapper/selector_generator.rb

@@ -42,10 +42,6 @@ module Praxis::Mapper
       association[:local_key_columns].each {|col| add_select(col) }
       
       node = SelectorGeneratorNode.new(associated_resource)
-      if association[:remote_key_columns].nil?
-        binding.pry
-        puts association
-      end
       unless association[:remote_key_columns].empty?
         # Make sure we add the required columns for this association to the remote model query
         fields = {} if fields == true

data/lib/praxis/multipart/part.rb

@@ -28,6 +28,10 @@ module Praxis
       self
     end
 
+    def self.json_schema_type
+      :object
+    end
+
     def self.example(context=nil, options:{})
       if (payload_attribute = options[:payload_attribute])
         payload = payload_attribute.example(context + ['payload'])
@@ -52,8 +56,7 @@ module Praxis
                headers_attribute: headers_attribute,
                filename_attribute: filename_attribute)
     end
-
-
+    
     def self.describe(shallow=true, example: nil, options:{})
       hash = super(shallow, example: example)
 

data/lib/praxis/response_definition.rb

@@ -163,7 +163,7 @@ module Praxis
           end
         end
 
-        content[:payload] = payload
+        content[:payload] = {type: payload}
       end
 
       unless parts == nil

data/lib/praxis/tasks/api_docs.rb

@@ -62,5 +62,28 @@ namespace :praxis do
       generator.save!
     end
 
+    desc "Generate OpenAPI 3 docs for a Praxis App"
+    task :openapi => [:environment] do |t, args|
+      require 'fileutils'
+
+      Praxis::Blueprint.caching_enabled = false
+      generator = Praxis::Docs::OpenApiGenerator.new(Dir.pwd)
+      generator.save!
+    end
+
+    desc "Preview (and Generate) OpenAPI 3 docs for a Praxis App"
+    task :openapipreview => [:openapi] do |t, args|
+      require 'webrick' 
+      docs_port = 9090
+      root = Dir.pwd + '/docs/openapi/'
+      wb = Thread.new do
+        s = WEBrick::HTTPServer.new(:Port => docs_port, :DocumentRoot => root)
+        trap('INT') { s.shutdown }
+        s.start
+      end
+      `open http://localhost:#{docs_port}/`
+      wb.join
+    end
+
   end
 end

data/lib/praxis/types/media_type_common.rb

@@ -14,6 +14,16 @@ module Praxis
           hash
         end
 
+        def as_json_schema(**args)
+          the_type = @attribute && @attribute.type || member_type
+          the_type.as_json_schema(args)
+        end
+
+        def json_schema_type
+          the_type = @attribute && @attribute.type || member_type
+          the_type.json_schema_type
+        end
+    
         def description(text=nil)
           @description = text if text
           @description

data/lib/praxis/types/multipart_array.rb

@@ -153,6 +153,68 @@ module Praxis
         example
       end
 
+      def self.json_schema_type
+        :object
+      end
+
+      # Multipart request bodies are special in OPEN API
+      # schema:            # Request payload
+      # type: object
+      # properties:      # Request parts
+      #   id:            # Part 1 (string value)
+      #     type: string
+      #     format: uuid
+      #   address:       # Part2 (object)
+      #     type: object
+      #     properties:
+      #       street:
+      #         type: string
+      #       city:
+      #         type: string
+      #   profileImage:  # Part 3 (an image)
+      #     type: string
+      #     format: binary
+      # 
+      # NOTE: not sure if this 
+      def self.as_openapi_request_body( attribute_options: {} )
+        hash = { type: json_schema_type }
+        opts = self.options.merge( attribute_options )
+        hash[:description] = opts[:description] if opts[:description]
+        hash[:default] = opts[:default] if opts[:default]
+
+        unless self.attributes.empty?
+          props = {}
+          encoding = {}
+          self.attributes.each do |part_name, part_attribute|
+            part_example = part_attribute.example
+            key_to_use = part_name.is_a?(Regexp) ? part_name.source : part_name
+            
+            part_info = {}
+            if (payload_attribute = part_attribute.options[:payload_attribute])
+              props[key_to_use] = payload_attribute.as_json_schema(example: part_example.payload)
+            end
+            #{
+            # contentType: 'fff',
+            # headers: {
+            #   custom1: 'safd'
+            # }
+            if (headers_attribute = part_attribute.options[:headers_attribute])
+              # Does this 'Content-Type' string check work?...can it be a symbol? what does it mean anyway?
+              encoding[key_to_use][:contentType] = headers_attribute['Content-Type'] if headers_attribute['Content-Type']
+              # TODO?rethink? ...is this correct?: att a 'headers' key with some header schemas if this part have some
+              encoding[key_to_use]['headers'] = headers_attribute.as_json_schema(example: part_example.headers)
+            end
+          end
+
+          hash[:properties] = props
+          hash[:encoding] = encoding unless encoding.empty?
+        end
+        hash
+      end
+
+      def self.as_json_schema( shallow: false, example: nil, attribute_options: {} )
+        as_openapi_request_body(attribute_options: attribute_options)
+      end
 
       def self.describe(shallow=true, example: nil)
         type_name = Attributor.type_name(self)

data/lib/praxis/version.rb

@@ -1,3 +1,3 @@
 module Praxis
-  VERSION = '2.0.pre.4'
+  VERSION = '2.0.pre.5'
 end

data/praxis.gemspec

@@ -24,8 +24,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'mustermann', '>=1.1', '<=2'
   spec.add_dependency 'activesupport', '>= 3'
   spec.add_dependency 'mime', '~> 0'
-  spec.add_dependency 'praxis-blueprints', '>= 3.4'
-  spec.add_dependency 'attributor', '>= 5.4'
+  spec.add_dependency 'praxis-blueprints', '>= 3.5'
+  spec.add_dependency 'attributor', '>= 5.5'
   spec.add_dependency 'thor'
   spec.add_dependency 'terminal-table', '~> 1.4'
 

data/spec/praxis/response_definition_spec.rb

@@ -514,12 +514,11 @@ describe Praxis::ResponseDefinition do
 
     context 'for a definition with a media type' do
       let(:media_type) { Instance }
-      subject(:payload) { output[:payload] }
+      subject(:payload) { output[:payload][:type] }
 
       before do
         response.media_type Instance
       end
-
       its([:name]) { should eq 'Instance' }
       context 'examples' do
         subject(:examples) { payload[:examples] }
@@ -571,7 +570,9 @@ describe Praxis::ResponseDefinition do
         end
 
         it{ should be_kind_of(::Hash) }
-        its([:payload]){ should ==  {id: 'Praxis-SimpleMediaType', name: 'Praxis::SimpleMediaType', family: 'string', identifier: 'foobar' } }
+        it 'has the right type info' do
+          expect(subject[:payload][:type]).to match(id: 'Praxis-SimpleMediaType', name: 'Praxis::SimpleMediaType', family: 'string', identifier: 'foobar')
+        end
         its([:status]){ should == 200 }
       end
       context 'using a full response definition block' do
@@ -587,7 +588,9 @@ describe Praxis::ResponseDefinition do
         end
 
         it{ should be_kind_of(::Hash) }
-        its([:payload]) { should == {id: 'Praxis-SimpleMediaType', name: 'Praxis::SimpleMediaType', family: 'string', identifier: 'custom_media'} }
+        it 'has the right type info' do
+          expect(subject[:payload][:type]).to match(id: 'Praxis-SimpleMediaType', name: 'Praxis::SimpleMediaType', family: 'string', identifier: 'custom_media')
+        end
         its([:status]) { should == 234 }
       end
     end

data/spec/spec_app/design/api.rb

@@ -27,6 +27,12 @@ Praxis::ApiDefinition.define do
     produces 'json','xml'
     #version_with :path
     #base_path "/v:api_version"
+
+    # Custom attributes (for OpenApi, for example)
+    termsOfService "http://example.com/tos"
+    contact name: 'Joe', email: 'joe@email.com'
+    license name: "Apache 2.0",
+            url: "https://www.apache.org/licenses/LICENSE-2.0.html"
   end
 
   info '1.0' do # Applies to 1.0 version (and inherits everything else form the global one)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: praxis
 version: !ruby/object:Gem::Version
-  version: 2.0.pre.4
+  version: 2.0.pre.5
 platform: ruby
 authors:
 - Josep M. Blanquer
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-05 00:00:00.000000000 Z
+date: 2020-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -79,28 +79,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.4'
+        version: '3.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.4'
+        version: '3.5'
 - !ruby/object:Gem::Dependency
   name: attributor
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.4'
+        version: '5.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.4'
+        version: '5.5'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -540,6 +540,18 @@ files:
 - lib/praxis/dispatcher.rb
 - lib/praxis/docs/generator.rb
 - lib/praxis/docs/link_builder.rb
+- lib/praxis/docs/open_api_generator.rb
+- lib/praxis/docs/openapi/info_object.rb
+- lib/praxis/docs/openapi/media_type_object.rb
+- lib/praxis/docs/openapi/operation_object.rb
+- lib/praxis/docs/openapi/parameter_object.rb
+- lib/praxis/docs/openapi/paths_object.rb
+- lib/praxis/docs/openapi/request_body_object.rb
+- lib/praxis/docs/openapi/response_object.rb
+- lib/praxis/docs/openapi/responses_object.rb
+- lib/praxis/docs/openapi/schema_object.rb
+- lib/praxis/docs/openapi/server_object.rb
+- lib/praxis/docs/openapi/tag_object.rb
 - lib/praxis/error_handler.rb
 - lib/praxis/exception.rb
 - lib/praxis/exceptions/config.rb