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

data/lib/praxis/resource_definition.rb

@@ -95,14 +95,6 @@ module Praxis
         @on_finalize
       end
 
-      # FIXME: this is inconsistent with the rest of the magic DSL convention.
-      def routing(&block)
-        warn "DEPRECATED: ResourceDefinition.routing is deprecated use prefix directly instead."
-
-        # eval this assuming it will only call #prefix
-        self.instance_eval(&block)
-      end
-
       def prefix(prefix=nil)
         return @prefix if prefix.nil?
         @routing_prefix = nil # reset routing_prefix
@@ -125,7 +117,7 @@ module Praxis
         @routing_prefix = nil # reset routing_prefix
 
         parent_action = parent.canonical_path
-        parent_route = parent_action.primary_route.path
+        parent_route = parent_action.route.path
 
         # if a mapping is passed, it *must* resolve any param name conflicts
         unless mapping.any?
@@ -146,7 +138,7 @@ module Praxis
           if mapping.key?(name)
             param = mapping[name]
             # FIXME: this won't handle URI Template type paths, ie '/{parent_id}'
-            prefixed_path = parent_action.primary_route.prefixed_path
+            prefixed_path = parent_action.route.prefixed_path
             @parent_prefix = prefixed_path.gsub(/(:)(#{name})(\W+|$)/, "\\1#{param.to_s}\\3")
           else
             mapping[name] = name
@@ -221,14 +213,14 @@ module Praxis
       end
 
       def to_href( params )
-        canonical_path.primary_route.path.expand(params.transform_values(&:to_s))
+        canonical_path.route.path.expand(params)
       end
 
       def parse_href(path)
         if path.kind_of?(::URI::Generic)
           path = path.path
         end
-        param_values = canonical_path.primary_route.path.params(path)
+        param_values = canonical_path.route.path.params(path)
         attrs = canonical_path.params.attributes
         param_values.each_with_object({}) do |(key,value),hash|
           hash[key.to_sym] = attrs[key.to_sym].load(value,[key])

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/route.rb

@@ -1,13 +1,12 @@
 module Praxis
 
   class Route
-    attr_accessor :verb, :path, :version, :name, :prefixed_path, :options
+    attr_accessor :verb, :path, :version, :prefixed_path, :options
 
-    def initialize(verb, path, version='n/a', name:nil, prefixed_path:nil, **options)
+    def initialize(verb, path, version='n/a', prefixed_path:nil, **options)
       @verb = verb
       @path = path
       @version = version
-      @name = name
       @options = options
       @prefixed_path = prefixed_path
     end
@@ -34,7 +33,6 @@ module Praxis
         path: path.to_s,
         version: version
       }
-      result[:name] = name unless name.nil?
       result[:options] = options if options.any?
       result
     end

data/lib/praxis/routing_config.rb

@@ -1,7 +1,7 @@
 module Praxis
   class RoutingConfig
 
-    attr_reader :routes
+    attr_reader :route
     attr_reader :version
     attr_reader :base
 
@@ -10,7 +10,7 @@ module Praxis
       @base = base
       @prefix_segments = Array(prefix)
 
-      @routes = []
+      @route = nil
 
       if block_given?
         instance_eval(&block)
@@ -53,12 +53,8 @@ module Praxis
       end
       prefixed_path = path.gsub('//','/')
       path = (base + path).gsub('//','/')
-      # Reject our own options
-      route_name = options.delete(:name);
-      pattern = Mustermann.new(path, **{ignore_unknown_options: true}.merge( options ))
-      route = Route.new(verb, pattern, version, name: route_name, prefixed_path: prefixed_path, **options)
-      @routes << route
-      route
+      pattern = Mustermann.new(path, {ignore_unknown_options: true}.merge( options ))
+      @route = Route.new(verb, pattern, version, prefixed_path: prefixed_path, **options)
     end
 
   end

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/tasks/routes.rb

@@ -7,7 +7,7 @@ namespace :praxis do
     table = Terminal::Table.new title: "Routes",
     headings:  [
       "Version", "Path", "Verb",
-      "Resource", "Action", "Implementation", "Name", "Primary", "Options"
+      "Resource", "Action", "Implementation", "Options"
     ]
 
     rows = []
@@ -27,24 +27,20 @@ namespace :praxis do
           implementation: method_name,
         }
 
-        if action.routes.empty?
+        unless action.route
           warn "Warning: No routes defined for #{resource_definition.name}##{name}."
           rows << row
         else
-          action.routes.each do |route|
-            rows << row.merge({
-              version: route.version,
-              verb: route.verb,
-              path: route.path,
-              name: route.name,
-              primary: (action.primary_route == route ? 'yes' : ''),
-              options: route.options
-            })
+          route = action.route
+          rows << row.merge({
+            version: route.version,
+            verb: route.verb,
+            path: route.path,
+            options: route.options
+          })
         end
       end
     end
-  end
-
     case args[:format] || "table"
     when "json"
       puts JSON.pretty_generate(rows)
@@ -52,7 +48,7 @@ namespace :praxis do
       rows.each do |row|
         formatted_options = row[:options].map{|(k,v)| "#{k}:#{v.to_s}"}.join("\n")
         row_data = row.values_at(:version, :path, :verb, :resource,
-                                    :action, :implementation, :name, :primary)
+                                    :action, :implementation)
         row_data << formatted_options
         table.add_row(row_data)
       end
@@ -60,6 +56,5 @@ namespace :praxis do
     else
       raise "unknown output format: #{args[:format]}"
     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/validation_handler.rb

@@ -3,8 +3,7 @@ module Praxis
 
     # Should return the Response to send back
     def handle!(summary:, request:, stage:, errors: nil, exception: nil, **opts)
-      documentation = Docs::LinkBuilder.instance.for_request request
-      Responses::ValidationError.new(summary: summary, errors: errors, exception: exception, documentation: documentation, **opts)
+      Responses::ValidationError.new(summary: summary, errors: errors, exception: exception, **opts)
     end
 
   end

data/lib/praxis/version.rb

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

data/praxis.gemspec

@@ -24,14 +24,14 @@ 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'
 
   spec.add_development_dependency 'bundler'
-  spec.add_development_dependency 'rake', '~> 0.9'
-  spec.add_development_dependency 'rake-notes', '~> 0'
+  spec.add_development_dependency 'rake', '>= 12.3.3'
+  
   if RUBY_PLATFORM !~ /java/
     spec.add_development_dependency 'pry'
     spec.add_development_dependency 'pry-byebug'
@@ -49,7 +49,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rack-test', '~> 0'
   spec.add_development_dependency 'simplecov', '~> 0'
   spec.add_development_dependency 'fuubar', '~> 2'
-  spec.add_development_dependency 'yard', ">= 0.9.20"
   spec.add_development_dependency 'coveralls'
   # Just for the query selector extensions etc...
   spec.add_development_dependency 'sequel', '~> 5'

data/spec/functional_spec.rb

@@ -331,12 +331,15 @@ describe 'Functional specs' do
   end
 
   context 'wildcard verb routing' do
+    let(:content_type){ 'application/json' }
     it 'can terminate instances with POST' do
-      post '/api/clouds/23/instances/1/terminate?api_version=1.0', '', 'global_session' => session
+      post '/api/clouds/23/instances/1/terminate?api_version=1.0', nil, 'CONTENT_TYPE' => content_type, 'global_session' => session
+      puts last_response.body
+      #binding.pry
       expect(last_response.status).to eq(200)
     end
     it 'can terminate instances with DELETE' do
-      post '/api/clouds/23/instances/1/terminate?api_version=1.0', '', 'global_session' => session
+      post '/api/clouds/23/instances/1/terminate?api_version=1.0', nil, 'CONTENT_TYPE' => content_type, 'global_session' => session
       expect(last_response.status).to eq(200)
     end
 
@@ -355,7 +358,7 @@ describe 'Functional specs' do
 
   context 'auth_plugin' do
     it 'can terminate' do
-      post '/api/clouds/23/instances/1/terminate?api_version=1.0', '', 'global_session' => session
+      post '/api/clouds/23/instances/1/terminate?api_version=1.0', nil, 'global_session' => session
       expect(last_response.status).to eq(200)
     end
 
@@ -366,8 +369,8 @@ describe 'Functional specs' do
   end
 
   context 'with mismatch between Content-Type and payload' do
-    let(:body) { '{}' }
-    let(:content_type) { 'application/x-www-form-urlencoded' }
+    let(:body) { 'some-text' }
+    let(:content_type) { 'application/json' }
 
     before do
       post '/api/clouds/1/instances/2/terminate?api_version=1.0', body, 'CONTENT_TYPE' => content_type, 'global_session' => session
@@ -376,7 +379,7 @@ describe 'Functional specs' do
     it 'returns a useful error message' do
       body = JSON.parse(last_response.body)
       expect(body['name']).to eq('ValidationError')
-      expect(body['summary']).to match("Error loading payload. Used Content-Type: 'application/x-www-form-urlencoded'")
+      expect(body['summary']).to match("Error loading payload. Used Content-Type: 'application/json'")
       expect(body['errors']).to_not be_empty
     end
   end

data/spec/praxis/action_definition_spec.rb

@@ -115,7 +115,7 @@ describe Praxis::ActionDefinition do
     end
 
     its('params.attributes.keys') { should eq [:inherited, :app_name, :name, :one]}
-    its('routes.first.path.to_s') { should eq '/api/foobars/hello_world/test_trait/:app_name/:one' }
+    its('route.path.to_s') { should eq '/api/foobars/hello_world/test_trait/:app_name/:one' }
     its(:traits) { should eq [:test] }
 
     it 'is reflected in the describe output' do
@@ -231,7 +231,7 @@ describe Praxis::ActionDefinition do
       let(:parent_param) { ApiResources::Volumes.actions[:show].params.attributes[:id] }
 
       it 'has the right path' do
-        expect(action.primary_route.path.to_s).to eq '/api/clouds/:cloud_id/volumes/:volume_id/snapshots/:id'
+        expect(action.route.path.to_s).to eq '/api/clouds/:cloud_id/volumes/:volume_id/snapshots/:id'
       end
 
       its('params.attributes'){ should have_key(:cloud_id) }
@@ -281,22 +281,10 @@ describe Praxis::ActionDefinition do
     subject(:action) { resource_definition.actions[:show] }
 
     it 'works' do
-      expansion = action.primary_route.path.expand(cloud_id:'232', id: '2')
+      expansion = action.route.path.expand(cloud_id:232, id: 2)
       expect(expansion).to eq "/api/clouds/232/instances/2"
     end
 
-    context '#primary_route' do
-      it 'is the first-defined route' do
-        expect(action.primary_route).to be(action.routes.first)
-      end
-    end
-
-    context '#named_routes' do
-      subject(:named_routes) { action.named_routes }
-
-      its([:alternate]) { should be(action.routes[1]) }
-    end
-
   end
 
   context 'with nodoc!' do
@@ -339,7 +327,7 @@ describe Praxis::ActionDefinition do
       allow(Praxis::ApiDefinition).to receive(:instance).and_return(non_singleton_api)
     end
 
-    its('routes.first.path.to_s') { should eq '/apps/:app_name/foobars/hello_world/:one' }
+    its('route.path.to_s') { should eq '/apps/:app_name/foobars/hello_world/:one' }
     its('params.attributes.keys') { should match_array [:inherited, :app_name, :one]}
 
     context 'where the action overrides a base_param' do

data/spec/praxis/api_general_info_spec.rb

@@ -17,8 +17,8 @@ describe Praxis::ApiGeneralInfo do
       endpoint 'api.example.com'
       base_path "/base"
 
-      consumes 'xml', 'x-www-form-urlencoded'
-      produces 'json', 'x-www-form-urlencoded'
+      consumes 'json'
+      produces 'json'
 
       base_params do
         attribute :name, String
@@ -40,8 +40,8 @@ describe Praxis::ApiGeneralInfo do
     end
 
     its(:name) { should eq 'Name' }
-    its(:consumes) { should eq ['xml', 'x-www-form-urlencoded']}
-    its(:produces) { should eq ['json', 'x-www-form-urlencoded']}
+    its(:consumes) { should eq ['json']}
+    its(:produces) { should eq ['json']}
   end
 
   context '.describe' do
@@ -59,8 +59,8 @@ describe Praxis::ApiGeneralInfo do
     its([:base_params, :name, :type, :name]) { should eq 'String' }
     its([:version_with]) { should eq([:header, :params]) }
     its([:endpoint]) { should eq 'api.example.com' }
-    its([:consumes]) { should eq ['xml', 'x-www-form-urlencoded'] }
-    its([:produces]) { should eq ['json', 'x-www-form-urlencoded'] }
+    its([:consumes]) { should eq ['json'] }
+    its([:produces]) { should eq ['json'] }
   end
 
   context 'base_path with versioning' do