serega 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52535c7fab3897f65aec4e156ab5681e8595b4519df1e79a777688cee486a480
-  data.tar.gz: 16adbd9f036b0e23928049df873966f264db1004d2c4c1bc9e28422d687efd12
+  metadata.gz: f11821b5953500ef9f895ad8c96e97951734615363f3147c623b70519b6199a5
+  data.tar.gz: 8b03241a9def2e5a8777a75e61062f8b81544e497a1a1e490e085d52f14a326c
 SHA512:
-  metadata.gz: 93a6aaefdf954556e31bd604ead1e376d5ffbb74225251e635bf5133af53da26f47e924f1f88349fa4656e228ddca573347d9f8fa15cc30bc6052f7e5dfec3bd
-  data.tar.gz: c84135d04c79aae1ccd03a3f3ac7dbed53dbf75165575afbb61ad6e32a558318cac2a8311c31b76df90fb74823facdf4677821d8f7ae8284f04782d33b04ad41
+  metadata.gz: eb5cb48e74c0e9c8307c6ceb6c47b918eb46ef3c160de90d0eb976239bbc036f1d3fb78219abd5567977f348e3e03d7e492e29140e6d85223fcf14289d794d89
+  data.tar.gz: acb7623ea317aab640aae70d0a5dfa0c436b706529741b36b15d938ab6af7523576f72ab4633b591b61dcdc38df768818eab3811005c248c3a00d2872cdccc46

data/README.md

@@ -888,6 +888,107 @@ Look at [select serialized fields](#selecting-fields) for `:hide` usage examples
  end
 ```
 
+### Plugin :openapi
+
+Helps to build OpenAPI schemas
+
+This schemas can be easily used with [rswag](https://github.com/rswag/rswag#referenced-parameters-and-schema-definitions)"
+gem by adding them to "config.swagger_docs"
+
+Schemas properties will have no any "type" or other limits specified by default,
+you should provide them as new attribute `:openapi` option.
+
+This plugin adds type "object" or "array" only for relationships and marks
+attributes as **required** if they have no `:hide` option set
+(manually or automatically).
+
+After enabling this plugin attributes with :serializer option will have
+to have `:many` option set to construct "object" or "array" openapi
+property type.
+
+- constructing all serializers schemas:
+  `Serega::OpenAPI.schemas`
+- constructing specific serializers schemas:
+  `Serega::OpenAPI.schemas(Serega::OpenAPI.serializers - [MyBaseSerializer])`
+- constructing one serializer schema:
+  `SomeSerializer.openapi_schema`
+
+```ruby
+  class BaseSerializer < Serega
+    plugin :openapi
+  end
+
+  class UserSerializer < BaseSerializer
+    attribute :name, openapi: { type: "string" }
+
+    openapi_properties(
+      name: { type: :string }
+    )
+  end
+
+  class PostSerializer < BaseSerializer
+    attribute :text, openapi: { type: "string" }
+    attribute :user, serializer: UserSerializer, many: false
+    attribute :comments, serializer: PostSerializer, many: true, hide: true
+
+    openapi_properties(
+      text: { type: :string },
+      user: { type: 'object' }, # `$ref` added automatically
+      comments: { type: 'array' } # `items` option with `$ref` added automatically
+    )
+  end
+
+  puts Serega::OpenAPI.schemas
+  # =>
+  # {
+  #   "PostSerializer" => {
+  #     type: "object",
+  #     properties: {
+  #       text: {type: "string"},
+  #       user: {:$ref => "#/components/schemas/UserSerializer"},
+  #       comments: {type: "array", items: {:$ref => "#/components/schemas/PostSerializer"}}
+  #     },
+  #     required: [:text, :comments],
+  #     additionalProperties: false
+  #   },
+  #   "UserSerializer" => {
+  #     type: "object",
+  #     properties: {
+  #       name: {type: "string"}
+  #     },
+  #     required: [:name],
+  #     additionalProperties: false
+  #   }
+  # }
+```
+
+### Plugin :explicit_many_option
+
+Plugin requires to add :many option when adding relationships
+(relationships are attributes with :serializer option specified)
+
+Adding this plugin makes clearer to find if relationship returns array or single
+object
+
+Also plugin `:openapi` load this plugin automatically as it need to know if
+relationship is array
+
+```ruby
+  class BaseSerializer < Serega
+    plugin :explicit_many_option
+  end
+
+  class UserSerializer < BaseSerializer
+    attribute :name
+  end
+
+  class PostSerializer < BaseSerializer
+    attribute :text
+    attribute :user, serializer: UserSerializer, many: false
+    attribute :comments, serializer: PostSerializer, many: true
+  end
+```
+
 ## Errors
 
 - `Serega::SeregaError` is a base error raised by this gem.

data/VERSION

@@ -1 +1 @@
-0.12.0
+0.14.0

data/lib/serega/plugins/explicit_many_option/explicit_many_option.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    #
+    # Plugin :explicit_many_option
+    #
+    # Plugin requires to add :many option when adding relationships
+    # (relationships are attributes with :serializer option specified)
+    #
+    # Adding this plugin makes clearer to find if relationship returns array or single object
+    #
+    # Also some plugins like :openapi load this plugin automatically as they need to know if
+    # relationship is array
+    #
+    # @example
+    #   class BaseSerializer < Serega
+    #     plugin :explicit_many_option
+    #   end
+    #
+    #   class UserSerializer < BaseSerializer
+    #     attribute :name
+    #   end
+    #
+    #   class PostSerializer < BaseSerializer
+    #     attribute :text
+    #     attribute :user, serializer: UserSerializer, many: false
+    #     attribute :comments, serializer: PostSerializer, many: true
+    #   end
+    #
+    module ExplicitManyOption
+      # @return [Symbol] Plugin name
+      def self.plugin_name
+        :explicit_many_option
+      end
+
+      #
+      # Applies plugin code to specific serializer
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param _opts [Hash] Loaded plugins options
+      #
+      # @return [void]
+      #
+      def self.load_plugin(serializer_class, **_opts)
+        require_relative "./validations/check_opt_many"
+
+        serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
+      end
+
+      #
+      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
+      #
+      # @see Serega::SeregaValidations::CheckAttributeParams
+      #
+      module CheckAttributeParamsInstanceMethods
+        private
+
+        def check_opts
+          super
+
+          CheckOptMany.call(opts)
+        end
+      end
+    end
+
+    register_plugin(ExplicitManyOption.plugin_name, ExplicitManyOption)
+  end
+end

data/lib/serega/plugins/explicit_many_option/validations/check_opt_many.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module ExplicitManyOption
+      #
+      # Validator for attribute :many option
+      #
+      class CheckOptMany
+        class << self
+          #
+          # Checks attribute :many option must be provided with relations
+          #
+          # @param opts [Hash] Attribute options
+          #
+          # @raise [SeregaError] Attribute validation error
+          #
+          # @return [void]
+          #
+          def call(opts)
+            serializer = opts[:serializer]
+            return unless serializer
+
+            many_option_exists = opts.key?(:many)
+            return if many_option_exists
+
+            raise SeregaError,
+              "Attribute option :many [Boolean] must be provided" \
+              " for attributes with :serializer option"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/openapi/lib/modules/config.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module OpenAPI
+      #
+      # Config class additional/patched instance methods
+      #
+      # @see Serega::SeregaConfig
+      #
+      module ConfigInstanceMethods
+        #
+        # Returns openapi plugin config
+        #
+        # @return [Serega::SeregaPlugins::OpenAPI::OpenAPIConfig] configuration for openapi plugin
+        #
+        def openapi
+          @openapi ||= OpenAPIConfig.new(self.class.serializer_class, opts.fetch(:openapi))
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/openapi/lib/openapi_config.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module OpenAPI
+      #
+      # OpenAPI plugin config
+      #
+      class OpenAPIConfig
+        attr_reader :serializer_class, :opts
+
+        def initialize(serializer_class, opts)
+          @serializer_class = serializer_class
+          @opts = opts
+        end
+
+        #
+        # Saves new properties
+        #
+        # @param new_properties [Hash] new properties
+        #
+        # @return [Hash] OpenAPI properties
+        #
+        def properties(new_properties = FROZEN_EMPTY_HASH)
+          properties = opts[:properties]
+          return properties if new_properties.empty?
+
+          new_properties = SeregaUtils::EnumDeepDup.call(new_properties)
+          symbolize_keys!(new_properties)
+
+          new_properties.each do |attribute_name, new_attribute_properties|
+            check_attribute_exists(attribute_name)
+            check_properties_is_a_hash(attribute_name, new_attribute_properties)
+
+            properties[attribute_name] = symbolize_keys!(new_attribute_properties)
+          end
+        end
+
+        #
+        # @return [#call] builder of `$ref` attribute
+        #
+        def ref_builder
+          opts[:ref_builder]
+        end
+
+        #
+        # Sets new $ref option builder
+        #
+        # @param builder [#call] Callable object that accepts serializer_class and constructs $ref option string
+        #
+        # @return Specified new builder
+        #
+        def ref_builder=(builder)
+          raise SeregaError, "ref_builder must respond to #call" unless builder.respond_to?(:call)
+          opts[:ref_builder] = builder
+        end
+
+        #
+        # @return [#call] builder of schema name
+        #
+        def schema_name_builder
+          opts[:schema_name_builder]
+        end
+
+        #
+        # Sets new schema_name_builder
+        #
+        # @param builder [#call] Callable object that accepts serializer_class and
+        #   constructs schema name to use in schemas list and in $ref option
+        #
+        # @return Specified new builder
+        #
+        def schema_name_builder=(builder)
+          raise SeregaError, "schema_name_builder must respond to #call" unless builder.respond_to?(:call)
+          opts[:schema_name_builder] = builder
+        end
+
+        private
+
+        def check_attribute_exists(attribute_name)
+          return if serializer_class.attributes.key?(attribute_name)
+
+          raise SeregaError, "No attribute with name :#{attribute_name}"
+        end
+
+        def check_properties_is_a_hash(attribute_name, new_attribute_properties)
+          return if new_attribute_properties.is_a?(Hash)
+
+          raise SeregaError, "Property #{attribute_name} value must be a Hash," \
+            " but #{new_attribute_properties.inspect} was provided"
+        end
+
+        def symbolize_keys!(opts)
+          opts.transform_keys! do |key|
+            key.to_sym
+          end
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/openapi/openapi.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Utility class to build OpenAPI schemas
+  #
+  class OpenAPI
+    #
+    # Constructs OpenAPI schemas for multiple serializers
+    #
+    # @params serializers [Class<Serega>] Serializers tobuild schemas,
+    #   by default it is all serializers with :openapi plugin enabled
+    #
+    # @return [Hash] Schemas hash
+    #
+    def self.schemas(serializers = self.serializers)
+      serializers.each_with_object({}) do |serializer_class, schemas|
+        schema = serializer_class.openapi_schema
+        schema_name = serializer_class.openapi_schema_name
+        schemas[schema_name] = schema
+      end
+    end
+
+    #
+    # Returns list of serializers with :openapi plugin
+    #
+    def self.serializers
+      @serializers ||= []
+    end
+  end
+
+  module SeregaPlugins
+    #
+    # Plugin :openapi
+    #
+    # Helps to build OpenAPI schemas
+    #
+    # This schemas can be easielty used with "rswag" gem by adding them to "config.swagger_docs"
+    #   https://github.com/rswag/rswag#referenced-parameters-and-schema-definitions
+    #
+    # This plugin only adds type "object" or "array" for relationships and marks
+    # attributes as **required** if they have no :hide option set.
+    #
+    # OpenAPI properties will have no any "type" or other options specified by default,
+    # you should provide them in 'YourSerializer.openapi_properties' method.
+    # `openapi_properties` can be specified multiple time, in this case they wil be merged.
+    #
+    # After enabling this plugin attributes with :serializer option will have
+    # to have :many option set to construct "object" or "array" openapi type for relationships.
+    #
+    # OpenAPI `$ref` property will be added automatically for all relationships.
+    #
+    # Example constructing all serializers schemas:
+    #   `Serega::OpenAPI.schemas`
+    #
+    # Example constructing specific serializers schemas:
+    #   `Serega::OpenAPI.schemas(Serega::OpenAPI.serializers - [MyBaseSerializer])`
+    #
+    # Example constructing one serializer schema:
+    #   `SomeSerializer.openapi_schema`
+    #
+    # @example
+    #   class BaseSerializer < Serega
+    #     plugin :openapi
+    #   end
+    #
+    #   class UserSerializer < BaseSerializer
+    #     attribute :name
+    #
+    #     openapi_properties(
+    #       name: { type: :string }
+    #     )
+    #   end
+    #
+    #   class PostSerializer < BaseSerializer
+    #     attribute :text
+    #     attribute :user, serializer: UserSerializer, many: false
+    #     attribute :comments, serializer: PostSerializer, many: true, hide: true
+    #
+    #     openapi_properties(
+    #       text: { type: :string },
+    #       user: { type: 'object' }, # `$ref` option will be added automatically when constructing schema
+    #       comments: { type: 'array' } # `items` option with `$ref` will be added automatically when constructing schema
+    #     )
+    #   end
+    #
+    #   puts Serega::OpenAPI.schemas
+    #   =>
+    #   {
+    #     "PostSerializer" => {
+    #       type: "object",
+    #       properties: {
+    #         text: {type: "string"},
+    #         user: {:$ref => "#/components/schemas/UserSerializer"},
+    #         comments: {type: "array", items: {:$ref => "#/components/schemas/PostSerializer"}}
+    #       },
+    #       required: [:text, :comments],
+    #       additionalProperties: false
+    #     },
+    #     "UserSerializer" => {
+    #       type: "object",
+    #       properties: {
+    #         name: {type: "string"}
+    #       },
+    #       required: [:name],
+    #       additionalProperties: false
+    #     }
+    #   }
+    #
+    module OpenAPI
+      # Builder for schema name (used is schemas list). Returns serializer class name
+      DEFAULT_SCHEMA_NAME_BUILDER = ->(serializer_class) { serializer_class.name }
+
+      # Builder for $ref openapi property
+      DEFAULT_REF_BUILDER = ->(serializer_class) { "#/components/schemas/#{serializer_class.openapi_schema_name}" }
+
+      # @return [Symbol] Plugin name
+      def self.plugin_name
+        :openapi
+      end
+
+      # Checks requirements and loads additional plugins
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param opts [Hash] loaded plugins opts
+      #
+      # @return [void]
+      #
+      def self.before_load_plugin(serializer_class, **opts)
+        unless serializer_class.plugin_used?(:explicit_many_option)
+          serializer_class.plugin :explicit_many_option
+        end
+      end
+
+      #
+      # Applies plugin code to specific serializer
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param _opts [Hash] Loaded plugins options
+      #
+      # @return [void]
+      #
+      def self.load_plugin(serializer_class, **opts)
+        require_relative "./lib/modules/config"
+        require_relative "./lib/openapi_config"
+
+        serializer_class.extend(ClassMethods)
+        serializer_class::SeregaConfig.include(ConfigInstanceMethods)
+
+        config = serializer_class.config
+        config.opts[:openapi] = {properties: {}}
+        openapi_config = serializer_class.config.openapi
+        openapi_config.schema_name_builder = opts[:schema_name_builder] || DEFAULT_SCHEMA_NAME_BUILDER
+        openapi_config.ref_builder = opts[:ref_builder] || DEFAULT_REF_BUILDER
+      end
+
+      #
+      # Adds config options and runs other callbacks after plugin was loaded
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param opts [Hash] loaded plugins opts
+      #
+      # @return [void]
+      #
+      def self.after_load_plugin(serializer_class, **opts)
+        Serega::OpenAPI.serializers << serializer_class unless serializer_class.equal?(Serega)
+      end
+
+      #
+      # Serega additional/patched class methods
+      #
+      # @see Serega
+      #
+      module ClassMethods
+        #
+        # OpenAPI schema for current serializer
+        #
+        def openapi_schema
+          properties = SeregaUtils::EnumDeepDup.call(openapi_properties)
+          required_properties = []
+
+          attributes.each do |attribute_name, attribute|
+            add_openapi_property(properties, attribute_name, attribute)
+            add_openapi_required_property(required_properties, attribute_name, attribute)
+          end
+
+          {
+            type: "object",
+            properties: properties,
+            required: required_properties,
+            additionalProperties: false
+          }
+        end
+
+        #
+        # Adds new OpenAPI properties and returns all properties
+        #
+        # @param props [Hash] Specifies new properties
+        #
+        # @return [Hash] Specified OpenAPI properties
+        #
+        def openapi_properties(props = FROZEN_EMPTY_HASH)
+          config.openapi.properties(props)
+        end
+
+        #
+        # Builds OpenAPI schema name using configured builder
+        #
+        # @return [String] OpenAPI schema name
+        #
+        def openapi_schema_name
+          config.openapi.schema_name_builder.call(self)
+        end
+
+        private
+
+        def inherited(subclass)
+          super
+          Serega::OpenAPI.serializers << subclass
+        end
+
+        def add_openapi_property(properties, attribute_name, attribute)
+          property = properties[attribute_name] ||= {}
+          return unless attribute.relation?
+
+          ref = attribute.serializer.config.openapi.ref_builder.call(attribute.serializer)
+
+          if attribute.many
+            property[:type] = "array"
+            property[:items] ||= {}
+            property[:items][:$ref] ||= ref
+          else
+            property[:$ref] ||= ref
+          end
+        end
+
+        def add_openapi_required_property(required_properties, attribute_name, attribute)
+          required_properties << attribute_name unless attribute.hide
+        end
+      end
+    end
+
+    register_plugin(OpenAPI.plugin_name, OpenAPI)
+  end
+end

data/lib/serega/plugins/preloads/lib/preloads_config.rb

@@ -11,11 +11,11 @@ class Serega
         attr_reader :opts
 
         #
-        # Initializes context_metadata config object
+        # Initializes PreloadsConfig object
         #
         # @param opts [Hash] options
         #
-        # @return [Serega::SeregaPlugins::Metadata::MetadataConfig]
+        # @return [Serega::SeregaPlugins::Preloads::PreloadsConfig]
         #
         def initialize(opts)
           @opts = opts

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Andrey Glushkov
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-10 00:00:00.000000000 Z
+date: 2023-07-24 00:00:00.000000000 Z
 dependencies: []
 description: |
   JSON Serializer
@@ -59,6 +59,8 @@ files:
 - lib/serega/plugins/batch/lib/validations/check_batch_opt_loader.rb
 - lib/serega/plugins/batch/lib/validations/check_opt_batch.rb
 - lib/serega/plugins/context_metadata/context_metadata.rb
+- lib/serega/plugins/explicit_many_option/explicit_many_option.rb
+- lib/serega/plugins/explicit_many_option/validations/check_opt_many.rb
 - lib/serega/plugins/formatters/formatters.rb
 - lib/serega/plugins/if/if.rb
 - lib/serega/plugins/if/validations/check_opt_if.rb
@@ -72,6 +74,9 @@ files:
 - lib/serega/plugins/metadata/validations/check_opt_hide_nil.rb
 - lib/serega/plugins/metadata/validations/check_opts.rb
 - lib/serega/plugins/metadata/validations/check_path.rb
+- lib/serega/plugins/openapi/lib/modules/config.rb
+- lib/serega/plugins/openapi/lib/openapi_config.rb
+- lib/serega/plugins/openapi/openapi.rb
 - lib/serega/plugins/preloads/lib/format_user_preloads.rb
 - lib/serega/plugins/preloads/lib/modules/attribute.rb
 - lib/serega/plugins/preloads/lib/modules/attribute_normalizer.rb
@@ -117,7 +122,7 @@ metadata:
   source_code_uri: https://github.com/aglushkov/serega
   documentation_uri: https://www.rubydoc.info/gems/serega
   changelog_uri: https://github.com/aglushkov/serega/blob/master/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -132,8 +137,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.7
-signing_key: 
+rubygems_version: 3.4.6
+signing_key:
 specification_version: 4
 summary: JSON Serializer
 test_files: []