openapi_blocks 0.3.1 → 0.5.0

data/lib/generators/openapi_blocks/openapi/templates/openapi.rb.tt

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class <%= class_name %>Openapi < OpenapiBlocks::Controller
+  # resource <%= class_name %>Serializer
+  # controller <%= class_name %>Controller
+
+  # tags "<%= class_name.pluralize %>"
+
+  # operation :index do
+  #   summary     "List all <%= class_name.pluralize.downcase %>"
+  #   description "Returns a paginated list of <%= class_name.pluralize.downcase %>"
+  #
+  #   parameter :page,     in: :query, type: :integer, description: "Page number"
+  #   parameter :per_page, in: :query, type: :integer, description: "Items per page"
+  #
+  #   response 200, description: "List of <%= class_name.pluralize.downcase %>", schema: { type: :array, items: :<%= class_name %> }
+  #   response 401, description: "Unauthorized"
+  # end
+
+  # operation :show do
+  #   summary "Get a <%= class_name.downcase %>"
+  #
+  #   response 200, description: "<%= class_name %> found",     schema: :<%= class_name %>
+  #   response 404, description: "<%= class_name %> not found"
+  # end
+
+  # operation :create do
+  #   summary "Create a <%= class_name.downcase %>"
+  #
+  #   response 201, description: "<%= class_name %> created", schema: :<%= class_name %>
+  #   response 422, description: "Invalid data"
+  # end
+
+  # operation :update do
+  #   summary "Update a <%= class_name.downcase %>"
+  #
+  #   response 200, description: "<%= class_name %> updated",     schema: :<%= class_name %>
+  #   response 404, description: "<%= class_name %> not found"
+  #   response 422, description: "Invalid data"
+  # end
+
+  # operation :destroy do
+  #   summary "Delete a <%= class_name.downcase %>"
+  #
+  #   response 200, description: "<%= class_name %> deleted"
+  #   response 404, description: "<%= class_name %> not found"
+  # end
+end

data/lib/generators/openapi_blocks/serializer/serializer_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  module Generators
+    class SerializerGenerator < Rails::Generators::NamedBase # rubocop:disable Style/Documentation
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an OpenapiBlocks Serializer class in app/serializers/"
+
+      def create_serializer_file
+        template "serializer.rb.tt", "app/serializers/#{file_name}_serializer.rb"
+      end
+    end
+  end
+end

data/lib/generators/openapi_blocks/serializer/templates/serializer.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class <%= class_name %>Serializer < OpenapiBlocks::Serializer
+  # model <%= class_name %> is inferred automatically from the class name
+
+  # ignore :password_digest, :reset_password_token
+
+  # association :posts, type: :array, read_only: true
+  # association :company
+
+  # attribute :full_name, type: :string, read_only: true
+  # def full_name
+  #   "#{object.first_name} #{object.last_name}"
+  # end
+end

data/lib/openapi_blocks/auto_serialize.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  module AutoSerialize # rubocop:disable Style/Documentation
+    def render(options = nil, extra = nil, &) # rubocop:disable Metrics/MethodLength
+      if auto_serialize_candidate?(options)
+        object     = options[:json]
+        serializer = Registry.resolve(object)
+
+        if serializer
+          log_serializer(object, serializer)
+          options = options.merge(json: serializer.serialize(object))
+        else
+          warn_no_serializer(object)
+        end
+      end
+
+      super
+    end
+
+    private
+
+    def auto_serialize_candidate?(options)
+      OpenapiBlocks.configuration.auto_serialize &&
+        options.is_a?(Hash) &&
+        options.key?(:json)
+    end
+
+    def log_serializer(object, serializer)
+      model = extract_model(object)
+      Rails.logger.debug(
+        "[OpenapiBlocks] #{model.name} serialized by #{serializer.name}"
+      )
+    end
+
+    def warn_no_serializer(object)
+      model = extract_model(object)
+      return unless model
+
+      Rails.logger.warn(
+        "[OpenapiBlocks] No serializer found for #{model.name}. " \
+        "Falling back to default Rails rendering. " \
+        "Create #{model.name}Serializer or use `serializes #{model.name}` explicitly."
+      )
+    end
+
+    def extract_model(object)
+      case object
+      when Array then object.first&.class
+      else object.respond_to?(:klass) ? object.klass : object.class
+      end
+    end
+  end
+end

data/lib/openapi_blocks/base.rb

@@ -1,48 +1,19 @@
 # frozen_string_literal: true
 
 module OpenapiBlocks
-  class Base # rubocop:disable Style/Documentation
-    include Serializer
+  # <b>DEPRECATED:</b> please use <tt>OpenapiBlocks::Controllers</tt> and <tt>OpenapiBlocks::Resources</tt> instead.
+  class Base
+    include Concerns::Schemable
+    include Concerns::Documentable
+    include Serialization
 
     class << self
-      attr_reader :_model, :_ignored, :_associations, :_virtual_attributes, :_operations, :_tags
-
-      def model(klass = nil)
-        klass ? @_model = klass : @_model ||= infer_model # rubocop:disable Naming/MemoizedInstanceVariableName
-      end
-
-      def ignore(*attributes)
-        @_ignored ||= []
-        @_ignored.concat(attributes.map(&:to_s))
-      end
-
-      def association(name, type: nil, read_only: false)
-        @_associations ||= []
-        @_associations << { name: name, type: type, read_only: read_only }
-      end
-
-      def attribute(name, **)
-        @_virtual_attributes ||= []
-        @_virtual_attributes << ({ name: name, ** })
-      end
-
-      def operation(action, &block)
-        @_operations ||= {}
-        builder = OperationBuilder.new
-        builder.instance_eval(&block) if block
-        @_operations[action] = builder
-      end
-
-      def tags(*values)
-        values.any? ? @_tags = values : @_tags
-      end
-
       private
 
       def infer_model
         model_name = name
                      .gsub(/Openapi$/, "")
-                     .gsub(/Resource$/, "")
+                     .gsub(/Serializer$/, "")
                      .split("::")
                      .last
 

data/lib/openapi_blocks/builder.rb

@@ -4,21 +4,53 @@ require_relative "spec/document"
 
 module OpenapiBlocks
   class Builder # rubocop:disable Style/Documentation
+    REQUIRED_CONFIG_ERROR = <<~MSG
+      OpenapiBlocks is not configured. Add an initializer:
+
+        # config/initializers/openapi_blocks.rb
+        OpenapiBlocks.configure do |config|
+          config.openapi_version = "3.1.0"  # required: "3.0.3" or "3.1.0"
+
+          config.info do
+            title   "My API"   # required
+            version "1.0.0"    # required
+          end
+        end
+    MSG
+
     def self.build
       new.build
     end
 
     def build
+      validate_configuration!
       Spec::Document.new(openapi_classes).build
     end
 
     private
 
+    def validate_configuration! # rubocop:disable Metrics/CyclomaticComplexity
+      config = OpenapiBlocks.configuration
+      errors = []
+
+      unless config.configured?
+        errors << "config.openapi_version or config.info must be defined — call OpenapiBlocks.configure"
+      end
+      errors << "config.info.title is required"   if config.info&.title.blank?
+      errors << "config.info.version is required" if config.info&.version.blank?
+
+      return if errors.empty?
+
+      raise Error, "#{REQUIRED_CONFIG_ERROR}\nMissing:\n#{errors.map { |e| "  - #{e}" }.join("\n")}"
+    end
+
     def openapi_classes
       ObjectSpace.each_object(Class).select do |klass|
         name = Module.instance_method(:name).bind_call(klass)
-        name&.end_with?("Openapi") &&
-          (klass < OpenapiBlocks::Base || klass < OpenapiBlocks::Controller)
+        next unless name&.end_with?("Openapi")
+
+        klass < OpenapiBlocks::Base ||
+          klass < OpenapiBlocks::Controller
       end
     end
   end

data/lib/openapi_blocks/concerns/documentable.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  module Concerns
+    module Documentable # rubocop:disable Style/Documentation
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods # rubocop:disable Style/Documentation
+        attr_reader :_operations, :_tags
+
+        def operation(action, &block)
+          @_operations ||= {}
+          builder = OperationBuilder.new
+          builder.instance_eval(&block) if block
+          @_operations[action] = builder
+        end
+
+        def tags(*values)
+          values.any? ? @_tags = values : @_tags
+        end
+      end
+    end
+  end
+end

data/lib/openapi_blocks/concerns/schemable.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  module Concerns
+    module Schemable # rubocop:disable Style/Documentation
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods # rubocop:disable Style/Documentation
+        attr_reader :_model, :_ignored, :_associations, :_virtual_attributes, :_serializes
+
+        def model(klass = nil)
+          klass ? @_model = klass : @_model ||= infer_model # rubocop:disable Naming/MemoizedInstanceVariableName
+        end
+
+        def ignore(*attributes)
+          @_ignored ||= []
+          @_ignored.concat(attributes.map(&:to_s))
+        end
+
+        def association(name, type: nil, read_only: false)
+          @_associations ||= []
+          @_associations << { name: name, type: type, read_only: read_only }
+        end
+
+        def attribute(name, **)
+          @_virtual_attributes ||= []
+          @_virtual_attributes << { name: name, ** }
+        end
+
+        def serializes(*models)
+          @_serializes ||= []
+          @_serializes.concat(models)
+        end
+
+        private
+
+        def infer_model
+          raise NotImplementedError, "#{name} must implement infer_model"
+        end
+      end
+    end
+  end
+end

data/lib/openapi_blocks/configuration.rb

@@ -9,14 +9,20 @@ module OpenapiBlocks
     SUPPORTED_VERSIONS = %w[3.1.0 3.0.3].freeze
 
     attr_reader   :openapi_version
-    attr_accessor :watch
+    attr_accessor :watch, :auto_serialize
 
     def initialize
       @openapi_version = "3.1.0"
       @watch           = :development
+      @auto_serialize  = false
       @info            = InfoBuilder.new
       @servers         = []
       @security        = nil
+      @configured      = false
+    end
+
+    def configured?
+      @configured
     end
 
     def openapi_version=(version)
@@ -29,6 +35,7 @@ module OpenapiBlocks
     end
 
     def info(&block)
+      @configured = true if block
       @info.instance_eval(&block) if block
       @info
     end

data/lib/openapi_blocks/controller.rb

@@ -2,8 +2,10 @@
 
 module OpenapiBlocks
   class Controller # rubocop:disable Style/Documentation
+    include Concerns::Documentable
+
     class << self
-      attr_reader :_resource, :_operations, :_tags, :_controller_class
+      attr_reader :_resource, :_controller_class
 
       def resource(klass)
         @_resource = klass
@@ -13,32 +15,10 @@ module OpenapiBlocks
         @_controller_class = klass
       end
 
-      def model
-        @_resource&.model
-      end
-
-      def _associations
-        @_resource&._associations
-      end
-
-      def _virtual_attributes
-        @_resource&._virtual_attributes
-      end
-
-      def _ignored
-        @_resource&._ignored
-      end
-
-      def operation(action, &block)
-        @_operations ||= {}
-        builder = OperationBuilder.new
-        builder.instance_eval(&block) if block
-        @_operations[action] = builder
-      end
-
-      def tags(*values)
-        values.any? ? @_tags = values : @_tags
-      end
+      def model               = @_resource&.model
+      def _associations       = @_resource&._associations
+      def _virtual_attributes = @_resource&._virtual_attributes
+      def _ignored            = @_resource&._ignored
     end
   end
 end

data/lib/openapi_blocks/railtie.rb

@@ -4,16 +4,28 @@ require "rails"
 
 module OpenapiBlocks
   class Railtie < Rails::Railtie # rubocop:disable Style/Documentation
-    initializer "openapi_blocks.middleware" do |app|
-      app.middleware.use OpenapiBlocks::Middleware
+    generators do
+      require "generators/openapi_blocks/install/install_generator"
+      require "generators/openapi_blocks/openapi/openapi_generator"
+      require "generators/openapi_blocks/serializer/serializer_generator"
     end
 
     initializer "openapi_blocks.autoload", before: :set_autoload_paths do |app|
       app.config.eager_load_paths << app.root.join("app/openapi")
+      app.config.eager_load_paths << app.root.join("app/serializers")
     end
 
     config.to_prepare do
       Dir[Rails.root.join("app/openapi/**/*.rb")].each { |f| require f }
+      Dir[Rails.root.join("app/serializers/**/*.rb")].each { |f| require f }
+
+      if OpenapiBlocks.configuration.auto_serialize
+        [ActionController::Base, ActionController::API].each do |klass|
+          klass.include(OpenapiBlocks::AutoSerialize) unless klass.ancestors.include?(OpenapiBlocks::AutoSerialize)
+        end
+
+        OpenapiBlocks::Registry.build!
+      end
     end
   end
 end

data/lib/openapi_blocks/registry.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  module Registry # rubocop:disable Style/Documentation
+    @map   = {}
+    @mutex = Mutex.new
+
+    class << self
+      def register(model, serializer)
+        @mutex.synchronize { @map[model] = serializer }
+      end
+
+      def resolve(object)
+        model = extract_model(object)
+        @mutex.synchronize { @map[model] }
+      end
+
+      def build!
+        @mutex.synchronize { @map = {} }
+
+        serializer_classes.each do |klass|
+          register_by_convention(klass)
+          register_by_explicit(klass)
+        end
+      end
+
+      def reset!
+        @mutex.synchronize { @map = {} }
+      end
+
+      private
+
+      def serializer_classes
+        ObjectSpace.each_object(Class).select { |klass| safe_serializer?(klass) }
+      end
+
+      def register_by_convention(klass)
+        model_name = klass_name(klass)
+                     .gsub(/Serializer$/, "")
+                     &.split("::")
+                     &.last
+        return if model_name.blank?
+
+        model = Object.const_get(model_name)
+        return unless model < ActiveRecord::Base
+
+        register(model, klass)
+      rescue NameError
+        nil
+      end
+
+      def register_by_explicit(klass)
+        return unless klass.respond_to?(:_serializes) && klass._serializes&.any?
+
+        klass._serializes.each { |model| register(model, klass) }
+      end
+
+      def safe_serializer?(klass)
+        klass_name(klass)&.end_with?("Serializer") && klass < OpenapiBlocks::Serializer
+      rescue StandardError
+        false
+      end
+
+      def klass_name(klass)
+        Module.instance_method(:name).bind_call(klass)
+      end
+
+      def extract_model(object)
+        case object
+        when Array then object.first&.class
+        else            object.respond_to?(:klass) ? object.klass : object.class
+        end
+      end
+    end
+  end
+end