praxis 2.0.pre.27 → 2.0.pre.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71228b4dd69f45eb28f8fec8782eef94fc24bdf6bb164a707d19cfade5091ac7
-  data.tar.gz: 33e2fce254db25935827d67ccc394aa7b54039212e97eaa7aae89d9006e4d5fd
+  metadata.gz: e8f0514dd2a155733de0efe5586dd4b0409c70a9b385822b15e39934a7b83ea2
+  data.tar.gz: ff66561cdaadb84a9c97b83c044c423561b6506e10a31cf72d032dce73dcb50c
 SHA512:
-  metadata.gz: 4f1bb58917fe5070e9433acdc2c2b1cbc0341eb832331f399a08bc2138fc5080397326ec2755f7e9452ec4774e931842699c4a4fa9455e0ef1231a6532f2b2d9
-  data.tar.gz: 346dbe116bab1da666e6e38b5d8a7f3863c0dcd2c97736a762fc107eaf77d879b6e9f52e5569e5ee4e4e56207b14c87b21a0cd4e4e10a2f33a34177720c682e7
+  metadata.gz: 9bcb89e0426fb2e9e8ea51e7794a42f0a1ec6969fce436196da8c9d32697b232a02bddb0008400d51c6dc8b2d475e1122283da8644ed78bb448d759fbf4f2363
+  data.tar.gz: 5c0a71be2bb1043ccc4269ccfa258d01e93b66d4dfa2f69938f5a495d8a296a305d2b8051c84a6683343672a69cd01e20f717dc87f4bf5ca4049b587438a3194

data/CHANGELOG.md

@@ -2,7 +2,14 @@
 
 ## next
 
-## 2.0.pre.26
+## 2.0.pre.29
+  * Assorted set of fixes to generate cleaner and more compliant OpenApi documents.
+    * Mostly in the area of multipart generation, and requirements and nullability for OpenApi 3.0
+## 2.0.pre.28
+  * Enhance the mapper's Resource property to allow for a couple more powerful options using the `as:` keyword:
+    * `as: :self` will provide a way to map any further incoming fields on top of the already existing object. This is useful when we want to expose some properties for a resource, grouped within a sub structure, but that in reality they exist directly in the resource's underlying model (i.e., to organize the information of the model in a more structured/groupable way).
+    * `as: 'association1.association2'` allows us to traverse more than 1 association, and continue applying the incoming fields under that. This is commonly used when we want to expose a relationship on a resource, which is really coming from more than a single association level depth.
+## 2.0.pre.27
   * Introduce a new `as:` option for resource's `property`, to indicate that the underlying association method it is connected to, has a different name.
     * This also will create a delegation function for the property name, that instead of calling the underlying association on the record, and wrapping the result with a resource instance, it will simply call the aliased method name (which is likely gonna hit the autogenerated code for that properyty, unless we have overriden it)
     * With this change, the selector generator (i.e., the thing that looks at the incoming `fields` parameters and calculates which select and includes are necessary to query all the data we need), will be able to understand this aliasing cases, and properly pass along, and continue expanding any nested fields that are under the property name (before this, and further inner fields would be not included as soon as we hit a property that didn't have that direct association underneath).

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

@@ -45,15 +45,22 @@ module Praxis
 
           if example_payload
             examples_by_content_type = {}
-            rendered_payload = example_payload.dump
+            # We don't need to provide top-level examples for a multipart payload...each part
+            # will provide its own example (and assembling a proper structured example for the whole
+            # body isn't necessarily trivial based on the spec)
+            # If we need to, someday, we can create the rendered_paylod by calling MultipartArray.self.dump_for_openapi
+            # and properly complete that code to generate the appropriate thing, including the encoding etc...
+            unless type < Praxis::Types::MultipartArray
+              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
+              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
           end
 

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

@@ -23,13 +23,14 @@ module Praxis
           # 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
+          example_handlers = \
+            if attribute.type < Praxis::Types::MultipartArray
+              ident = MediaTypeIdentifier.load('multipart/form-data')
+              [{ ident.to_s => 'json' }] # Multipart content type
+            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),

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

@@ -31,7 +31,7 @@ module Praxis
 
         def dump_schema(shallow: false, allow_ref: false)
           # We will dump schemas for mediatypes by simply creating a reference to the components' section
-          if type < Attributor::Container
+          if type < Attributor::Container && ! (type < Praxis::Types::MultipartArray)
             if (type < Praxis::Blueprint || type < Attributor::Model) && allow_ref && !type.anonymous?
               # TODO: Do we even need a description?
               h = @attribute_options[:description] ? { 'description' => @attribute_options[:description] } : {}
@@ -47,10 +47,11 @@ module Praxis
               props = type.attributes.transform_values.with_index do |definition, index|
                 # if type has an attribute in its requirements all, then it should be marked as required here
                 field_name = type.attributes.keys[index]
-                definition.options.merge!(required: true) if required_attributes.include?(field_name)
                 OpenApi::SchemaObject.new(info: definition).dump_schema(allow_ref: true, shallow: shallow)
               end
-              h = { type: :object, properties: props } # TODO: Example?
+              h = { type: :object}
+              h[:properties] = props if props.presence
+              h[:required] = required_attributes unless required_attributes.empty?
             end
           else
             # OpenApi::SchemaObject.new(info:target).dump_schema(allow_ref: allow_ref, shallow: shallow)
@@ -61,12 +62,8 @@ module Praxis
 
           # Tag on OpenAPI specific requirements that aren't already added in the underlying JSON schema model
           # Nullable: (it seems we need to ensure there is a null option to the enum, if there is one)
-          if @attribute_options[:null]
-            h[:nullable] = @attribute_options[:null]
-            h[:enum] = h[:enum] + [nil] if h[:enum] && !h[:enum].include?(nil)
-          end
-          # Required: Mostly for request bodies
-          h[:required] = true if @attribute_options[:required]
+          is_nullable = @attribute_options[:null]
+          h[:nullable] = true if is_nullable
           h
 
           # # TODO: FIXME: return a generic object type if the passed info was weird.

data/lib/praxis/docs/open_api_generator.rb

@@ -117,10 +117,10 @@ module Praxis
           openapi: '3.0.2',
           info: info_object.dump,
           servers: [server_object.dump],
-          paths: paths_object.dump
+          paths: paths_object.dump,
+          security: [] # NOTE: No security definitions in Praxis. Leave it empty, to not anger linters
           # 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:

data/lib/praxis/mapper/selector_generator.rb

@@ -68,7 +68,24 @@ module Praxis
         # Always add the underlying association if we're overriding the name...
         if (praxis_compat_model = resource.model&.respond_to?(:_praxis_associations))
           aliased_as = resource.properties[name][:as]
-          add_association(aliased_as, fields) if resource.model._praxis_associations[aliased_as]
+          if aliased_as == :self
+            # Special keyword to add itself as the association, but still continue procesing the fields
+            # This is useful when we expose resource fields tucked inside another sub-struct, this way
+            # we can make sure that if the fields necessary to compute things inside the struct, they are preloaded
+            add(fields)
+          else
+            first, *rest = aliased_as.to_s.split('.').map(&:to_sym)
+
+            extended_fields = \
+              if rest.empty?
+                fields
+              else
+                rest.reverse.inject(fields) do |accum, prop|
+                  { prop => accum }
+                end
+              end
+            add_association(first, extended_fields) if resource.model._praxis_associations[first]
+          end
         end
         dependencies&.each do |dependency|
           # To detect recursion, let's allow mapping depending fields to the same name of the property

data/lib/praxis/multipart/part.rb

@@ -254,5 +254,10 @@ module Praxis
     ensure
       self.content_type = original_content_type
     end
+
+    def self.dump_for_openapi(example_part)
+      # TODO: This needs to be structured as OpenAPI requires it
+      raise "dumping a part for open api not implemented yet"
+    end
   end
 end

data/lib/praxis/types/multipart_array.rb

@@ -197,7 +197,7 @@ module Praxis
             encoding[key_to_use]['headers'] = headers_attribute.as_json_schema(example: part_example.headers)
           end
 
-          hash[:properties] = props
+          hash[:properties] = props if props.presence
           hash[:encoding] = encoding unless encoding.empty?
         end
         hash
@@ -370,6 +370,10 @@ module Praxis
         all_entities = parts.join("\r\n--#{boundary}\r\n")
         "--#{boundary}\r\n#{all_entities}\r\n--#{boundary}--\r\n"
       end
+
+      def self.dump_for_openapi(example)
+        example.map {|part| MultipartPart.dump_for_openapi(part)}
+      end
     end
   end
 end

data/lib/praxis/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Praxis
-  VERSION = '2.0.pre.27'
+  VERSION = '2.0.pre.29'
 end

data/praxis.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.executables << 'praxis'
 
   spec.add_dependency 'activesupport', '>= 3'
-  spec.add_dependency 'attributor', '>= 6.4'
+  spec.add_dependency 'attributor', '>= 6.5'
   spec.add_dependency 'mime', '~> 0'
   spec.add_dependency 'mustermann', '>=1.1'
   spec.add_dependency 'rack', '>= 1'

data/spec/praxis/mapper/selector_generator_spec.rb

@@ -236,6 +236,55 @@ describe Praxis::Mapper::SelectorGenerator do
         end
         it_behaves_like 'a proper selector'
       end
+      context 'Deep aliased underlying associations also follows any nested fields at the end of the chain...' do
+        let(:fields) do
+          {
+            parent_id: true,
+            deep_aliased_association: {
+              name: true
+            }
+          }
+        end
+        let(:selectors) do
+          {
+            model: SimpleModel,
+            columns: %i[parent_id simple_name], # No added_column, as it does not follow the dotted reference as properties, just associations
+            tracks: {
+              parent: {
+                model: ParentModel,
+                columns: %i[id],
+                tracks: {
+                  simple_children: {
+                    model: SimpleModel,
+                    columns: %i[parent_id simple_name]
+                  }
+                }
+              }
+            }
+          }
+        end
+        it_behaves_like 'a proper selector'
+      end
+      context 'Using self for the underlying association: follows any nested fields skipping the association name and still applies dependencies' do
+        let(:fields) do
+          {
+            parent_id: true,
+            sub_struct: {
+              display_name: true
+            }
+          }
+        end
+        let(:selectors) do
+          {
+            model: SimpleModel,
+            # Parent_id is because we asked for it at the top
+            # display_name because we asked for it under sub_struct, but it is marked as :self
+            # alway_necessary_attribute because it is a dependency of sub_struct
+            columns: %i[parent_id display_name alway_necessary_attribute]
+          }
+        end
+        it_behaves_like 'a proper selector'
+      end
     end
 
     context 'string associations' do

data/spec/support/spec_resources.rb

@@ -154,6 +154,9 @@ class SimpleResource < BaseResource
   property :deep_nested_deps, dependencies: ['parent.simple_children.other_model.parent.display_name']
   property :aliased_association, as: :other_model, dependencies: [:name]
   property :overriden_aliased_association, as: :other_model, dependencies: [:name]
+  property :deep_aliased_association, as: 'parent.simple_children' , dependencies: [:name]
+
+  property :sub_struct, as: :self, dependencies: [:alway_necessary_attribute]
 
   before(:update!, :do_before_update)
   around(:update!, :do_around_update_nested)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: praxis
 version: !ruby/object:Gem::Version
-  version: 2.0.pre.27
+  version: 2.0.pre.29
 platform: ruby
 authors:
 - Josep M. Blanquer
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-12-21 00:00:00.000000000 Z
+date: 2023-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -31,14 +31,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.4'
+        version: '6.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.4'
+        version: '6.5'
 - !ruby/object:Gem::Dependency
   name: mime
   requirement: !ruby/object:Gem::Requirement