rails_ninja 0.1.0

data/lib/rails_ninja/endpoint_group.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module RailsNinja
+  class EndpointGroup < ActionController::Metal
+    abstract!
+
+    def params
+      @params ||= begin
+        raw = request.path_parameters.merge(request.query_parameters).merge(request.request_parameters)
+        raw.deep_symbolize_keys
+      end
+    end
+
+    # --- Class-level DSL ---
+
+    class << self
+      # HTTP verb decorators
+      %i[get post put patch delete].each do |verb|
+        define_method(verb) do |path, **options|
+          self._pending_route = { verb: verb, path: path, **options }
+        end
+      end
+
+      # Schema definition DSL
+      def schema(name, &block)
+        klass = Class.new(Schema::Base)
+        klass.class_eval(&block)
+
+        # Register as a constant on this class so it's accessible by name
+        const_set(name, klass)
+        _schemas[name] = klass
+        klass
+      end
+
+      def ninja_headers(*args)
+        if args.any?
+          @_headers = args.flatten
+        else
+          @_headers
+        end
+      end
+
+      def _headers
+        @_headers || []
+      end
+
+      def before_action(method_name = nil, &block)
+        _before_actions << (method_name || block)
+      end
+
+      def _before_actions
+        @_before_actions ||= []
+      end
+
+      def tags(*args)
+        if args.any?
+          @_tags = args.flatten
+        else
+          @_tags
+        end
+      end
+
+      def _tags
+        @_tags
+      end
+
+      # Pull in endpoints from an Endpoint class
+      def include_endpoint(endpoint_class)
+        endpoint_class._endpoints.each do |op|
+          # Dup the operation so we don't mutate the Endpoint's own copy
+          local_op = op.dup
+          local_op.with_tags(_tags) if _tags
+
+          # Generate a unique dispatch name to avoid collisions when multiple endpoints share handler names
+          original_handler = local_op.display_handler
+          dispatch_name = _unique_handler_name(endpoint_class, original_handler)
+          local_op.with_handler(dispatch_name)
+
+          _endpoints << local_op
+
+          define_method(dispatch_name) do
+            endpoint_instance = @_ninja_handler_instance
+            result = endpoint_instance.public_send(original_handler)
+            if endpoint_instance.performed?
+              self.status = endpoint_instance.status
+              self.content_type = endpoint_instance.content_type
+              self.response_body = endpoint_instance.response_body
+            else
+              result
+            end
+            result
+          end
+        end
+      end
+
+      # Mount an EndpointGroup (or a single Endpoint) under a path prefix
+      def mount(group_class, prefix: "/")
+        if group_class.is_a?(Class) && group_class <= RailsNinja::API
+          raise Error,
+                "#{group_class.name || group_class.inspect} is a RailsNinja::API and cannot be mounted: " \
+                "an API is a standalone document (one API class per openapi.json). " \
+                "Group its endpoints in a RailsNinja::EndpointGroup and mount that instead."
+        end
+
+        unless group_class.is_a?(Class) && group_class <= RailsNinja::EndpointGroup
+          raise Error,
+                "mount expects a RailsNinja::EndpointGroup (or RailsNinja::Endpoint) class, got #{group_class.inspect}"
+        end
+
+        _mounted_groups << { group_class: group_class, prefix: prefix }
+
+        # Define dispatch methods for all endpoints in the mounted group tree
+        group_class._all_endpoints.each do |op|
+          original_handler = op.display_handler
+          mounted_class = op.api_class
+          dispatch_name = _unique_handler_name(mounted_class, original_handler)
+
+          define_method(dispatch_name) do
+            endpoint_instance = @_ninja_handler_instance
+            result = endpoint_instance.public_send(original_handler)
+            if endpoint_instance.performed?
+              self.status = endpoint_instance.status
+              self.content_type = endpoint_instance.content_type
+              self.response_body = endpoint_instance.response_body
+            else
+              result
+            end
+            result
+          end
+        end
+      end
+
+      def _unique_handler_name(source_class, handler)
+        # Class names are unique constants, so they disambiguate deterministically
+        # across processes (object_id changes per boot, polluting logs and routes).
+        # Anonymous classes (e.g. Class.new in tests) have no name, so fall back.
+        prefix = source_class.name&.underscore&.tr("/", "_") || "__ninja_#{source_class.object_id}"
+        :"#{prefix}__#{handler}"
+      end
+
+      # Storage
+      def _endpoints
+        @_endpoints ||= []
+      end
+
+      def _schemas
+        @_schemas ||= {}
+      end
+
+      def _mounted_groups
+        @_mounted_groups ||= []
+      end
+
+      def _pending_route
+        @_pending_route
+      end
+
+      def _pending_route=(route)
+        @_pending_route = route
+      end
+
+      # The decorator magic: when a method is defined after a verb call,
+      # pair them together as an endpoint
+      def method_added(method_name)
+        super
+        return if @_inside_method_added
+        return unless _pending_route
+
+        @_inside_method_added = true
+
+        pending = _pending_route
+        self._pending_route = nil
+
+        # Extra paths that route to the same handler but are flagged deprecated
+        # in the OpenAPI spec. Accepts a single path or an array of paths.
+        deprecated_paths = Array(pending.delete(:deprecated_paths))
+
+        route_def = pending.merge(handler: method_name, api_class: self)
+        _endpoints << Operation.new(**route_def)
+
+        deprecated_paths.each do |deprecated_path|
+          _endpoints << Operation.new(**route_def, path: deprecated_path, deprecated: true)
+        end
+
+        @_inside_method_added = false
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@_endpoints, [])
+        subclass.instance_variable_set(:@_schemas, (_schemas || {}).dup)
+        subclass.instance_variable_set(:@_mounted_groups, [])
+        subclass.instance_variable_set(:@_before_actions, (_before_actions || []).dup)
+      end
+
+      def _all_endpoints
+        endpoints = _endpoints.dup
+        _mounted_groups.each do |mounted|
+          endpoints.concat(mounted[:group_class]._all_endpoints)
+        end
+        endpoints
+      end
+    end
+
+    private
+
+    def head(status_code)
+      self.status = status_code
+      self.content_type = "application/json"
+      self.response_body = [MultiJson.dump(nil)]
+    end
+
+    def render_json(body, status: 200)
+      self.status = status
+      self.content_type = "application/json"
+      self.response_body = [MultiJson.dump(body)]
+    end
+  end
+end

data/lib/rails_ninja/errors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RailsNinja
+  class Error < StandardError; end
+
+  class ValidationError < Error
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors
+      super("Validation failed: #{errors.join(', ')}")
+    end
+  end
+
+  class NotFoundError < Error
+    def initialize(msg = "Not Found")
+      super
+    end
+  end
+end

data/lib/rails_ninja/openapi/generator.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+module RailsNinja
+  module OpenAPI
+    class Generator
+      def initialize(api_class)
+        @api_class = api_class
+      end
+
+      def to_hash
+        @schema_names = build_schema_names
+
+        components = { schemas: build_schemas }
+        if @api_class._openapi_security_schemes.any?
+          components[:securitySchemes] = @api_class._openapi_security_schemes
+        end
+
+        spec = {
+          openapi: "3.2.0",
+          info: {
+            title: @api_class._title || @api_class.name || "API",
+            version: @api_class._version || "0.1.0",
+          },
+          paths: build_paths,
+          components: components,
+        }
+        spec[:servers] = [{ url: @api_class._server }] if @api_class._server
+        if @api_class._openapi_security.any?
+          spec[:security] = @api_class._openapi_security.map { |name| { name => [] } }
+        end
+        spec
+      end
+
+      def to_json(*_args)
+        MultiJson.dump(to_hash)
+      end
+
+      private
+
+      def collect_routes(group_class = @api_class, prefix = "/")
+        routes = []
+
+        group_class._endpoints.each do |endpoint|
+          full_path = normalize_path("#{prefix}/#{endpoint.path}")
+          routes << { endpoint: endpoint, full_path: full_path }
+        end
+
+        group_class._mounted_groups.each do |mounted|
+          sub_prefix = normalize_path("#{prefix}/#{mounted[:prefix]}")
+          routes.concat(collect_routes(mounted[:group_class], sub_prefix))
+        end
+
+        routes
+      end
+
+      def normalize_path(path)
+        "/" + path.squeeze("/").gsub(%r{^/|/$}, "")
+      end
+
+      def build_paths
+        routes = collect_routes
+        grouped = routes.group_by { |r| r[:full_path] }
+
+        grouped.each_with_object({}) do |(path, path_routes), paths|
+          openapi_path = path.gsub(/:(\w+)/, '{\1}')
+          paths[openapi_path] = {}
+
+          path_routes.each do |route|
+            endpoint = route[:endpoint]
+            verb = endpoint.verb.to_s.downcase
+            body_verb = %w[get delete head].exclude?(verb)
+
+            operation = { summary: endpoint.summary }
+            operation[:tags] = endpoint.tags if endpoint.tags&.any?
+            operation[:responses] = build_responses(endpoint)
+            # Deprecated aliases share a handler with the primary endpoint; only the
+            # current path carries the operationId to keep it unique across the spec.
+            operation[:operationId] = build_operation_id(endpoint) unless endpoint.deprecated?
+            operation[:deprecated] = true if endpoint.deprecated?
+
+            if endpoint.request_schema && body_verb
+              operation[:requestBody] = build_request_body(endpoint.request_schema)
+            end
+
+            params = extract_path_params(path) + extract_header_params(endpoint)
+            params += extract_query_params(endpoint) unless body_verb
+            operation[:parameters] = params if params.any?
+
+            paths[openapi_path][verb] = operation
+          end
+        end
+      end
+
+      def build_responses(endpoint)
+        return { "200" => { description: "Successful response" } } if endpoint.responses_map.empty?
+
+        endpoint.responses_map.each_with_object({}) do |(status, schema), out|
+          schema_node = if schema.is_a?(Array)
+                          { type: "array", items: schema_ref(schema.first) }
+                        else
+                          schema_ref(schema)
+                        end
+
+          out[status.to_s] = {
+            description: response_description_for(status),
+            content: { "application/json" => { schema: schema_node } },
+          }
+        end
+      end
+
+      def response_description_for(status)
+        case status.to_i
+        when 200..299 then "Successful response"
+        when 400 then "Bad request"
+        when 401 then "Unauthorized"
+        when 403 then "Forbidden"
+        when 404 then "Not found"
+        when 409 then "Conflict"
+        when 422 then "Unprocessable entity"
+        when 429 then "Too many requests"
+        when 500..599 then "Server error"
+        else "Response"
+        end
+      end
+
+      def build_request_body(schema)
+        {
+          required: true,
+          content: {
+            "application/json" => {
+              schema: schema_ref(schema),
+            },
+          },
+        }
+      end
+
+      def schema_ref(type)
+        if type.is_a?(Schema::OneOf)
+          result = { "oneOf" => type.variants.map { |v| schema_ref(v) } }
+          if type.discriminator
+            result["discriminator"] = {
+              "propertyName" => type.discriminator.to_s,
+              "mapping" => discriminator_mapping(type),
+            }
+          end
+          result
+        elsif type.is_a?(Array)
+          { type: "array", items: schema_ref(type.first) }
+        elsif type <= Schema::Base
+          { "$ref" => "#/components/schemas/#{schema_name(type)}" }
+        else
+          SchemaRef.primitive_type(type)
+        end
+      end
+
+      def discriminator_mapping(one_of)
+        one_of.variants.each_with_object({}) do |variant, mapping|
+          field = variant._fields[one_of.discriminator]
+          next unless field&.default
+
+          mapping[field.default.to_s] = "#/components/schemas/#{schema_name(variant)}"
+        end
+      end
+
+      def extract_path_params(path)
+        path.scan(/:(\w+)/).flatten.map do |param|
+          { name: param, in: "path", required: true, schema: { type: "string" } }
+        end
+      end
+
+      def extract_query_params(endpoint)
+        return [] unless endpoint.request_schema
+
+        endpoint.request_schema._fields.map do |name, field|
+          { name: name.to_s, in: "query", required: field.required, schema: schema_ref(field.type) }
+        end
+      end
+
+      def extract_header_params(endpoint)
+        return [] unless endpoint.header_params&.any?
+
+        endpoint.header_params.map do |h|
+          { name: h[:name], in: "header", required: h[:required], schema: h[:schema] }
+        end
+      end
+
+      def build_operation_id(endpoint)
+        tag = endpoint.tags&.first
+        handler = endpoint.display_handler.to_s
+
+        if tag
+          prefix = tag
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .downcase
+          "#{prefix}_#{handler}"
+        else
+          handler
+        end
+      end
+
+      def schema_name(schema_class)
+        @schema_names[schema_class] || schema_class.name || schema_class.object_id.to_s
+      end
+
+      def build_schema_names
+        names = {}
+
+        collect_schema_sources.each do |api_class|
+          api_class._schemas.each do |short_name, schema_class|
+            name = short_name.to_s
+
+            next if names.key?(schema_class)
+
+            existing = names.values.find { |n| n == name }
+            if existing
+              raise Error, "Schema name clash: '#{name}' is defined in multiple API classes"
+            end
+
+            names[schema_class] = name
+          end
+        end
+
+        names
+      end
+
+      def build_schemas
+        collect_schemas.to_h do |schema_class|
+          [schema_name(schema_class), json_schema_for(schema_class)]
+        end
+      end
+
+      def json_schema_for(schema_class)
+        properties = {}
+        required = []
+
+        schema_class._fields.each do |name, field|
+          property = schema_ref(field.type)
+          property[:title] = schema_title(name)
+          property[:enum] = field.enum if field.enum
+          properties[name.to_s] = property
+          required << name.to_s if field.required
+        end
+
+        result = { type: "object", title: schema_name(schema_class), properties: properties }
+        result[:required] = required if required.any?
+        result
+      end
+
+      def schema_title(name)
+        name.to_s.split("_").map(&:capitalize).join(" ")
+      end
+
+      def collect_schemas
+        schemas = Set.new
+
+        collect_routes.each do |route|
+          endpoint = route[:endpoint]
+          walk_schema_tree(endpoint.request_schema, schemas) if endpoint.request_schema
+          endpoint.responses_map.each_value { |schema| walk_schema_tree(schema, schemas) }
+        end
+
+        schemas
+      end
+
+      def walk_schema_tree(type, schemas)
+        if type.is_a?(Schema::OneOf)
+          type.variants.each { |v| walk_schema_tree(v, schemas) }
+        elsif type.is_a?(Array)
+          walk_schema_tree(type.first, schemas)
+        elsif type.is_a?(Class) && type <= Schema::Base
+          return if schemas.include?(type)
+
+          schemas << type
+          type._fields.each_value { |field| walk_schema_tree(field.type, schemas) }
+        end
+      end
+
+      def collect_schema_sources
+        sources = Set.new
+
+        collect_routes.each do |route|
+          sources << route[:endpoint].api_class
+        end
+
+        sources
+      end
+    end
+  end
+end

data/lib/rails_ninja/openapi/schema_ref.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RailsNinja
+  module OpenAPI
+    module SchemaRef
+      module_function
+
+      def to_json_schema(type)
+        if type.is_a?(Array)
+          inner = type.first
+          {
+            type: "array",
+            items: to_json_schema(inner),
+          }
+        elsif type <= Schema::Base
+          { "$ref" => "#/components/schemas/#{type.name || type.object_id}" }
+        else
+          primitive_type(type)
+        end
+      end
+
+      def schema_to_json_schema(schema_class)
+        properties = {}
+        required = []
+
+        schema_class._fields.each do |name, field|
+          properties[name.to_s] = to_json_schema(field.type)
+          required << name.to_s if field.required
+        end
+
+        result = { type: "object", properties: properties }
+        result[:required] = required if required.any?
+        result
+      end
+
+      def primitive_type(type)
+        return type.openapi_schema if type.is_a?(Class) && type <= Types::BaseScalar
+
+        raise Error, "Unsupported schema type: #{type.inspect}"
+      end
+    end
+  end
+end

data/lib/rails_ninja/operation.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RailsNinja
+  class Operation
+    attr_reader :verb, :path, :handler, :display_handler, :api_class,
+                :request_schema, :responses_map, :tags, :summary, :header_params
+
+    def initialize(verb:, path:, handler:, api_class:, request: nil, response: nil, responses: nil,
+      tags: nil, summary: nil, headers: nil, deprecated: false)
+      @verb = verb
+      @path = path
+      @handler = handler
+      @display_handler = handler
+      @api_class = api_class
+      @request_schema = request
+      @responses_map = responses || (response ? { 200 => response } : {})
+      @tags = tags || api_class._tags || []
+      @summary = summary || handler.to_s.tr("_", " ").capitalize
+      @header_params = merge_headers(api_class._headers, headers)
+      @deprecated = deprecated
+    end
+
+    def deprecated?
+      @deprecated
+    end
+
+    def response_schema
+      responses_map[200]
+    end
+
+    def with_handler(new_handler)
+      @handler = new_handler
+      self
+    end
+
+    def with_tags(new_tags)
+      @tags = new_tags
+      self
+    end
+
+    def response_is_array?
+      response_schema.is_a?(Array)
+    end
+
+    def response_schema_class
+      response_is_array? ? response_schema.first : response_schema
+    end
+
+    private
+
+    def merge_headers(class_headers, endpoint_headers)
+      parsed_class = parse_headers(class_headers)
+      parsed_endpoint = parse_headers(endpoint_headers)
+
+      # Endpoint-level headers override class-level headers with the same name
+      merged = parsed_class.reject { |ch| parsed_endpoint.any? { |eh| eh[:name] == ch[:name] } }
+      merged + parsed_endpoint
+    end
+
+    def parse_headers(headers)
+      return [] if headers.nil?
+
+      Array(headers).filter_map do |h|
+        if h.is_a?(String)
+          { name: h, required: true, schema: { type: "string" } }
+        elsif h.is_a?(Hash)
+          { name: h[:name], required: h.fetch(:required, true), schema: { type: h.fetch(:type, "string") } }
+        end
+      end
+    end
+  end
+end

data/lib/rails_ninja/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RailsNinja
+  class Railtie < ::Rails::Railtie
+    initializer "rails_ninja.add_autoload_paths" do |app|
+      api_path = Rails.root.join("app/api")
+      if api_path.exist?
+        app.config.autoload_paths << api_path.to_s
+        app.config.eager_load_paths << api_path.to_s
+      end
+    end
+
+    rake_tasks do
+      load File.expand_path("tasks.rake", __dir__)
+    end
+  end
+end

data/lib/rails_ninja/response.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RailsNinja
+  module Response
+    module_function
+
+    def json(body, status: 200)
+      [status, { "content-type" => "application/json" }, [MultiJson.dump(body)]]
+    end
+
+    def html(body, status: 200)
+      [status, { "content-type" => "text/html" }, [body]]
+    end
+
+    def error(message, status:)
+      json({ error: message }, status: status)
+    end
+  end
+end

data/lib/rails_ninja/schema/field.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsNinja
+  module Schema
+    Field = Struct.new(:name, :type, :required, :default, :enum, keyword_init: true) do
+      def initialize(name:, type:, required: true, default: nil, enum: nil)
+        super
+      end
+    end
+  end
+end