rest_framework 1.0.0.beta1 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4261d5bdf6f4e59ffce35b2a5f36bafe104bddd9b9437f34b77b495acbeefac6
-  data.tar.gz: 84f0213bfd2d54777059049b87b84f2ff4c727c45838c130ec7382b5d1aa451c
+  metadata.gz: 12d9337d2e8abbdde98e25233fc2cd9d1b3596b0f65a8a5b3210eee5d5a571bd
+  data.tar.gz: e77d714a217b1ecc6ab24cdab384d7ce82d2680775e15e701fa4f1c2b2e8d88d
 SHA512:
-  metadata.gz: 2d2308561ba8ae8668f2e3fd83da4487d1b9ba3b4ca632c1be21fe6bfbf5cb88b8f0a661624dc97a837473263ae944a1231ef7c8b90284d8851b275780326886
-  data.tar.gz: 030d5acc028ae343486c30968c66b25ab91d5577a48f236ccf4766ee8675b75c1f83ca8cb3f442dd9a0be93209142acd1aa4ba7d5cfd7c318521bbdc91cb986b
+  metadata.gz: 93d22bc0db33b0b99876bcf193b8f72bf7d12072a46c34d82e735c11223cb711329c685bda323f2cb4e7383c490f298f2225efa674ced397a275bd59597177dc
+  data.tar.gz: 7d0f5375e43bb4c696f566c851875f00587175d5429a20b9e502350b46dc7d09a4398fedd3ddf91d9b02e3b0e8e262beb8198d5fbe8a267f1c02b5ec73b82a59

data/README.md

@@ -7,10 +7,12 @@
 
 A framework for DRY RESTful APIs in Ruby on Rails.
 
-**The Problem**: Building controllers for APIs usually involves writing a lot of redundant CRUD logic, and routing them can be obnoxious.
-Building and maintaining features like ordering, filtering, and pagination can be tedious.
+**The Problem**: Building controllers for APIs usually involves writing a lot of redundant CRUD
+logic, and routing them can be obnoxious. Building and maintaining features like ordering,
+filtering, and pagination can be tedious.
 
-**The Solution**: This framework implements browsable API responses, CRUD actions for your models, and features like ordering/filtering/pagination, so you can focus on building awesome APIs.
+**The Solution**: This framework implements browsable API responses, CRUD actions for your models,
+and features like ordering/filtering/pagination, so you can focus on your application logic.
 
 Website/Guide: [rails-rest-framework.com](https://rails-rest-framework.com)
 
@@ -38,7 +40,8 @@ bundle install
 
 This section provides some simple examples to quickly get you started using the framework.
 
-For the purpose of this example, you'll want to add an `api_controller.rb` to your controllers, as well as a directory for the resources:
+For the purpose of this example, you'll want to add an `api_controller.rb` to your controllers, as
+well as a directory for the resources:
 
 ```text
 controllers/
@@ -51,7 +54,8 @@ controllers/
 
 ### Controller Mixins
 
-The root `ApiController` can include any common behavior you want to share across all your API controllers:
+The root `ApiController` can include any common behavior you want to share across all your API
+controllers:
 
 ```ruby
 class ApiController < ApplicationController
@@ -59,24 +63,21 @@ class ApiController < ApplicationController
 
   # Setting up a paginator class here makes more sense than defining it on every child controller.
   self.paginator_class = RESTFramework::PageNumberPaginator
-
-  # The page_size attribute doesn't exist on the `BaseControllerMixin`, but for child controllers
-  # that include the `ModelControllerMixin`, they will inherit this attribute and will not overwrite
-  # it.
-  class_attribute(:page_size, default: 30)
+  self.page_size = 30
 end
 ```
 
-A root controller can provide actions that exist on the root of your API.
-It's best to define a dedicated root controller, rather than using the `ApiController` for this purpose, so that actions don't propagate to child controllers:
+A root controller can provide actions that exist on the root of your API. It's best to define a
+dedicated root controller, rather than using the `ApiController` for this purpose, so that actions
+don't propagate to child controllers:
 
 ```ruby
 class Api::RootController < ApiController
   self.extra_actions = {test: :get}
 
   def root
-    render_api(
-      {
+    render(
+      api: {
         message: "Welcome to the API.",
         how_to_authenticate: <<~END.lines.map(&:strip).join(" "),
           You can use this API with your normal login session. Otherwise, you can insert your API
@@ -88,7 +89,7 @@ class Api::RootController < ApiController
   end
 
   def test
-    render_api({message: "Hello, world!"})
+    render(api: {message: "Hello, world!"})
   end
 end
 ```
@@ -105,7 +106,7 @@ class Api::MoviesController < ApiController
   def first
     # Always use the bang method, since the framework will rescue `RecordNotFound` and return a
     # sensible error response.
-    render_api(self.get_records.first!)
+    render(api: self.get_records.first!)
   end
 
   def get_recordset
@@ -114,8 +115,8 @@ class Api::MoviesController < ApiController
 end
 ```
 
-When `fields` is nil, then it will default to all columns.
-The `fields` attribute can also be a hash to include or exclude fields rather than defining them manually:
+When `fields` is nil, then it will default to all columns. The `fields` attribute can also be a hash
+to include or exclude fields rather than defining them manually:
 
 ```ruby
 class Api::UsersController < ApiController
@@ -127,9 +128,10 @@ end
 
 ### Routing
 
-Use `rest_route` for non-resourceful controllers, or `rest_resource` / `rest_resources` resourceful routers.
-These routers add some features to the Rails builtin `resource`/`resources` routers, such as automatically routing extra actions defined on the controller.
-To route the root, use `rest_root`.
+Use `rest_route` for non-resourceful controllers, or `rest_resource` / `rest_resources` resourceful
+routers. These routers add some features to the Rails builtin `resource`/`resources` routers, such
+as automatically routing extra actions defined on the controller. To route the root, use
+`rest_root`.
 
 ```ruby
 Rails.application.routes.draw do
@@ -146,7 +148,9 @@ end
 
 ## Development/Testing
 
-After you clone the repository, cd'ing into the directory should create a new gemset if you are using RVM.
-Then run `bin/setup` to install the appropriate gems and set things up.
+After you clone the repository, cd'ing into the directory should create a new gemset if you are
+using RVM. Then run `bin/setup` to install the appropriate gems and set things up.
 
-The top-level `bin/rails` proxies all Rails commands to the test project, so you can operate it via the usual commands (e.g., `rails test`, `rails server` and `rails console`). For development, use `foreman start` to run the web server and the job queue.
+The top-level `bin/rails` proxies all Rails commands to the test project, so you can operate it via
+the usual commands (e.g., `rails test`, `rails server` and `rails console`). For development, use
+`foreman start` to run the web server and the job queue.

data/VERSION

@@ -1 +1 @@
-1.0.0.beta1
+1.0.0.rc1

data/lib/rest_framework/engine.rb

@@ -8,6 +8,12 @@ class RESTFramework::Engine < Rails::Engine
           *RESTFramework::EXTERNAL_UNSUMMARIZED_ASSETS.keys.map { |name| "rest_framework/#{name}" },
         ]
       end
+
+      if RESTFramework.config.register_api_renderer
+        ActionController::Renderers.add(:api) do |data, kwargs|
+          render_api(data, **kwargs)
+        end
+      end
     end
   end
 end

data/lib/rest_framework/filters/query_filter.rb

@@ -1,6 +1,34 @@
 # A simple filtering backend that supports filtering a recordset based on query parameters.
 class RESTFramework::Filters::QueryFilter < RESTFramework::Filters::BaseFilter
-  NIL_VALUES = ["nil", "null"].freeze
+  # Wrapper to indicate a type of query that must be negated with `where.not(...)`.
+  class Not
+    attr_reader :q
+
+    def initialize(q)
+      @q = q
+    end
+  end
+
+  PREDICATES = {
+    true: true,
+    false: false,
+    null: nil,
+    lt: ->(f, v) { {f => ...v} },
+    # `gt` must negate `lte` because Rails doesn't support `>` with endless ranges.
+    gt: ->(f, v) { Not.new({f => ..v}) },
+    lte: ->(f, v) { {f => ..v} },
+    gte: ->(f, v) { {f => v..} },
+    not: ->(f, v) { Not.new({f => v}) },
+    cont: ->(f, v) { ["#{f} LIKE ?", "%#{ActiveRecord::Base.sanitize_sql_like(v)}%"] },
+    in: ->(f, v) {
+      if v.is_a?(Array)
+        {f => v.map { |v| v == "null" ? nil : v }}
+      elsif v.is_a?(String)
+        {f => v.split(",").map { |v| v == "null" ? nil : v }}
+      end
+    },
+  }.freeze
+  PREDICATES_REGEX = /^(.*)_(#{PREDICATES.keys.join("|")})$/
 
   # Get a list of filter fields for the current action.
   def _get_fields
@@ -8,56 +36,97 @@ class RESTFramework::Filters::QueryFilter < RESTFramework::Filters::BaseFilter
     return @controller.class.filter_fields&.map(&:to_s) || @controller.get_fields
   end
 
-  # Filter params for keys allowed by the current action's filter_fields/fields config.
-  def _get_filter_params
+  # Helper to find a variation of a field using a predicate. For example, there could be a field
+  # called `age`, and if `age_lt` it passed, we should return `["age", "lt"]`. Otherwise, if
+  # something like `age` is passed, then we should return `["age", nil]`.
+  def parse_predicate(field)
+    if match = PREDICATES_REGEX.match(field)
+      field = match[1]
+      predicate = match[2]
+    end
+
+    return field, predicate
+  end
+
+  # Filter params for keys allowed by the current action's filter_fields/fields config and return a
+  # query config in the form of: `[base_query, pred_queries, includes]`.
+  def _get_query_config
     fields = self._get_fields
     includes = []
 
-    filter_params = @controller.request.query_parameters.select { |p, _|
-      # Remove any trailing `__in` from the field name.
-      field = p.chomp("__in")
+    # Predicate queries must be added to a separate list because multiple predicates can be used.
+    # E.g., `age_lt=10&age_gte=5` would transform to `[{age: ...10}, {age: 5..}]` to avoid conflict
+    # on the `age` key.
+    pred_queries = []
 
-      # Remove any associations whose sub-fields are not filterable.
-      if match = /(.*)\.(.*)/.match(field)
-        field, sub_field = match[1..2]
-        next false unless field.in?(fields)
+    base_query = @controller.request.query_parameters.map { |field, v|
+      # First, if field is a simple filterable field, return early.
+      if field.in?(fields)
+        next [field, v]
+      end
 
-        sub_fields = @controller.class.field_configuration[field][:sub_fields] || []
-        if sub_field.in?(sub_fields)
-          includes << field.to_sym
-          next true
-        end
+      # First, try to parse a simple predicate and check if it is filterable.
+      pred_field, predicate = self.parse_predicate(field)
+      if predicate && pred_field.in?(fields)
+        field = pred_field
+      else
+        # Last, try to parse a sub-field or sub-field w/predicate.
+        root_field, sub_field = field.split(".", 2)
+        _, pred_sub_field = pred_field.split(".", 2) if predicate
 
-        next false
-      end
+        # Check if sub-field or sub-field w/predicate is filterable.
+        if sub_field
+          next nil unless root_field.in?(fields)
 
-      next field.in?(fields)
-    }.map { |p, v|
-      # Convert fields ending in `__in` to array values.
-      if p.end_with?("__in")
-        p = p.chomp("__in")
-        v = v.split(",").map { |v| v.in?(NIL_VALUES) ? nil : v }
+          sub_fields = @controller.class.field_configuration[root_field][:sub_fields] || []
+          if sub_field.in?(sub_fields)
+            includes << root_field.to_sym
+            next [field, v]
+          elsif pred_sub_field && pred_sub_field.in?(sub_fields)
+            includes << root_field.to_sym
+            field = pred_field
+          else
+            next nil
+          end
+        else
+          next nil
+        end
       end
 
-      # Convert "nil" and "null" to nil.
-      v = nil if v.in?(NIL_VALUES)
+      # If we get here, we must have a predicate, either from a field or a sub-field. Transform the
+      # value into a query that can be used in the ActiveRecord `where` API.
+      cfg = PREDICATES[predicate.to_sym]
+      if cfg.is_a?(Proc)
+        pred_queries << cfg.call(field, v)
+      else
+        pred_queries << {field => cfg}
+      end
 
-      [p, v]
-    }.to_h.symbolize_keys
+      next nil
+    }.compact.to_h.symbolize_keys
 
-    return filter_params, includes
+    puts "GNS: #{base_query.inspect} #{pred_queries.inspect} #{includes.inspect}"
+    return base_query, pred_queries, includes
   end
 
   # Filter data according to the request query parameters.
   def filter_data(data)
-    filter_params, includes = self._get_filter_params
+    base_query, pred_queries, includes = self._get_query_config
 
-    if filter_params.any?
+    if base_query.any? || pred_queries.any?
       if includes.any?
         data = data.includes(*includes)
       end
 
-      return data.where(**filter_params)
+      data = data.where(**base_query) if base_query.any?
+
+      pred_queries.each do |q|
+        if q.is_a?(Not)
+          data = data.where.not(q.q)
+        else
+          data = data.where(q)
+        end
+      end
     end
 
     return data

data/lib/rest_framework/mixins/base_controller_mixin.rb

@@ -12,6 +12,7 @@ module RESTFramework::Mixins::BaseControllerMixin
     description: nil,
     version: nil,
     inflect_acronyms: ["ID", "IDs", "REST", "API", "APIs"].freeze,
+    openapi_include_children: false,
 
     # Options related to serialization.
     rescue_unknown_format_with: :json,
@@ -37,7 +38,7 @@ module RESTFramework::Mixins::BaseControllerMixin
 
   # Default action for API root.
   def root
-    render_api({message: "This is the API root."})
+    render(api: {message: "This is the API root."})
   end
 
   module ClassMethods
@@ -69,6 +70,119 @@ module RESTFramework::Mixins::BaseControllerMixin
       end
     end
     # :nocov:
+
+    def openapi_response_content_types
+      return @openapi_response_content_types ||= [
+        "text/html",
+        self.serialize_to_json ? "application/json" : nil,
+        self.serialize_to_xml ? "application/xml" : nil,
+      ].compact
+    end
+
+    def openapi_request_content_types
+      return @openapi_request_content_types ||= [
+        "application/json",
+        "application/x-www-form-urlencoded",
+        "multipart/form-data",
+      ]
+    end
+
+    def openapi_paths(routes, tag)
+      resp_cts = self.openapi_response_content_types
+      req_cts = self.openapi_request_content_types
+
+      return routes.group_by { |r| r[:concat_path] }.map { |concat_path, routes|
+        [
+          concat_path.gsub(/:([0-9A-Za-z_-]+)/, "{\\1}"),
+          routes.map { |route|
+            metadata = RESTFramework::ROUTE_METADATA[route[:path]] || {}
+            summary = metadata.delete(:label).presence || self.label_for(route[:action])
+            description = metadata.delete(:description).presence
+            extra_action = RESTFramework::EXTRA_ACTION_ROUTES.include?(route[:path])
+            error_response = {"$ref" => "#/components/responses/BadRequest"}
+            not_found_response = {"$ref" => "#/components/responses/NotFound"}
+            spec = {tags: [tag], summary: summary, description: description}.compact
+
+            # All routes should have a successful response.
+            spec[:responses] = {
+              200 => {content: resp_cts.map { |ct| [ct, {}] }.to_h, description: "Success"},
+            }
+
+            # Builtin POST, PUT, PATCH, and DELETE should have a 400 and 404 response.
+            if route[:verb].in?(["POST", "PUT", "PATCH", "DELETE"]) && !extra_action
+              spec[:responses][400] = error_response
+              spec[:responses][404] = not_found_response
+            end
+
+            # All POST, PUT, PATCH should have a request body.
+            if route[:verb].in?(["POST", "PUT", "PATCH"])
+              spec[:requestBody] ||= {
+                content: req_cts.map { |ct|
+                  [ct, {}]
+                }.to_h,
+              }
+            end
+
+            # Add remaining metadata as an extension.
+            spec["x-rrf-metadata"] = metadata if metadata.present?
+
+            next route[:verb].downcase, spec
+          }.to_h.merge(
+            {
+              parameters: routes.first[:route].required_parts.map { |p|
+                {
+                  name: p,
+                  in: "path",
+                  required: true,
+                  schema: {type: "integer"},
+                }
+              },
+            },
+          ),
+        ]
+      }.to_h
+    end
+
+    def openapi_document(request, route_group_name, routes)
+      server = request.base_url + request.original_fullpath.gsub(/\?.*/, "")
+
+      return {
+        openapi: "3.1.1",
+        info: {
+          title: self.get_title,
+          description: self.description,
+          version: self.version.to_s,
+        }.compact,
+        servers: [{url: server}],
+        paths: self.openapi_paths(routes, route_group_name),
+        tags: [{name: route_group_name, description: self.description}.compact],
+        components: {
+          schemas: {
+            "Error" => {
+              type: "object",
+              required: ["message"],
+              properties: {
+                message: {type: "string"}, errors: {type: "object"}, exception: {type: "string"}
+              },
+            },
+          },
+          responses: {
+            "BadRequest": {
+              description: "Bad Request",
+              content: self.openapi_response_content_types.map { |ct|
+                [ct, ct == "text/html" ? {} : {schema: {"$ref" => "#/components/schemas/Error"}}]
+              }.to_h,
+            },
+            "NotFound": {
+              description: "Not Found",
+              content: self.openapi_response_content_types.map { |ct|
+                [ct, ct == "text/html" ? {} : {schema: {"$ref" => "#/components/schemas/Error"}}]
+              }.to_h,
+            },
+          },
+        },
+      }.compact
+    end
   end
 
   def self.included(base)
@@ -105,6 +219,7 @@ module RESTFramework::Mixins::BaseControllerMixin
       base.rescue_from(
         ActionController::ParameterMissing,
         ActionController::UnpermittedParameters,
+        ActionDispatch::Http::Parameters::ParseError,
         ActiveRecord::AssociationTypeMismatch,
         ActiveRecord::NotNullViolation,
         ActiveRecord::RecordNotFound,
@@ -118,7 +233,7 @@ module RESTFramework::Mixins::BaseControllerMixin
     end
 
     # Use `TracePoint` hook to automatically call `rrf_finalize`.
-    unless RESTFramework.config.disable_auto_finalize
+    if RESTFramework.config.auto_finalize
       # :nocov:
       TracePoint.trace(:end) do |t|
         next if base != t.self
@@ -152,8 +267,8 @@ module RESTFramework::Mixins::BaseControllerMixin
       400
     end
 
-    render_api(
-      {
+    render(
+      api: {
         message: e.message,
         errors: e.try(:record).try(:errors),
         exception: RESTFramework.config.show_backtrace ? e.full_message : nil,
@@ -239,81 +354,36 @@ module RESTFramework::Mixins::BaseControllerMixin
     end
   end
 
-  # TODO: Might make this the default render method in the future.
+  # Compatibility alias for deprecated `api_response`.
   alias_method :api_response, :render_api
 
-  def openapi_metadata
-    response_content_types = [
-      "text/html",
-      self.class.serialize_to_json ? "application/json" : nil,
-      self.class.serialize_to_xml ? "application/xml" : nil,
-    ].compact
-    request_content_types = [
-      "application/json",
-      "application/xml",
-      "application/x-www-form-urlencoded",
-      "multipart/form-data",
-    ].compact
-    routes = self.route_groups.values[0]
-    server = request.base_url + request.original_fullpath.gsub(/\?.*/, "")
-
-    return {
-      openapi: "3.1.1",
-      info: {
-        title: self.class.get_title,
-        description: self.class.description,
-        version: self.class.version.to_s,
-      }.compact,
-      servers: [{url: server}],
-      paths: routes.group_by { |r| r[:concat_path] }.map { |concat_path, routes|
-        [
-          concat_path.gsub(/:([0-9A-Za-z_-]+)/, "{\\1}"),
-          routes.map { |route|
-            metadata = route[:route].defaults[:metadata] || {}
-            summary = metadata[:label].presence || self.class.label_for(route[:action])
-            description = metadata[:description].presence
-            remaining_metadata = metadata.except(:label, :description).presence
-
-            [
-              route[:verb].downcase,
-              {
-                summary: summary,
-                description: description,
-                responses: {
-                  200 => {
-                    content: response_content_types.map { |ct|
-                      [ct, {}]
-                    }.to_h,
-                    description: "",
-                  },
-                },
-                requestBody: route[:verb].in?(["GET", "DELETE", "OPTIONS", "TRACE"]) ? nil : {
-                  content: request_content_types.map { |ct|
-                    [ct, {}]
-                  }.to_h,
-                },
-                "x-rrf-metadata": remaining_metadata,
-              }.compact,
-            ]
-          }.to_h.merge(
-            {
-              parameters: routes.first[:route].required_parts.map { |p|
-                {
-                  name: p,
-                  in: "path",
-                  required: true,
-                  schema: {type: "integer"},
-                }
-              },
-            },
-          ),
-        ]
-      }.to_h,
-    }.compact
+  def openapi_document
+    first, *rest = self.route_groups.to_a
+    document = self.class.openapi_document(request, *first)
+
+    if self.class.openapi_include_children
+      rest.each do |route_group_name, routes|
+        controller = "#{routes.first[:route].defaults[:controller]}_controller".camelize.constantize
+        child_document = controller.openapi_document(request, route_group_name, routes)
+
+        # Merge child paths and tags into the parent document.
+        document[:paths].merge!(child_document[:paths])
+        document[:tags] += child_document[:tags]
+
+        # If the child document has schemas, merge them into the parent document.
+        if schemas = child_document.dig(:components, :schemas)  # rubocop:disable Style/Next
+          document[:components] ||= {}
+          document[:components][:schemas] ||= {}
+          document[:components][:schemas].merge!(schemas)
+        end
+      end
+    end
+
+    return document
   end
 
   def options
-    render_api(self.openapi_metadata)
+    render(api: self.openapi_document)
   end
 end
 

data/lib/rest_framework/mixins/bulk_model_controller_mixin.rb

@@ -6,7 +6,7 @@ module RESTFramework::Mixins::BulkCreateModelMixin
   # While bulk update/destroy are obvious because they create new router endpoints, bulk create
   # overloads the existing collection `POST` endpoint, so we add a special key to the OpenAPI
   # metadata to indicate bulk create is supported.
-  def openapi_metadata
+  def openapi_document
     return super.merge({"x-rrf-bulk-create": true})
   end
 
@@ -14,7 +14,7 @@ module RESTFramework::Mixins::BulkCreateModelMixin
     if params[:_json].is_a?(Array)
       records = self.create_all!
       serialized_records = self.bulk_serialize(records)
-      return render_api(serialized_records)
+      return render(api: serialized_records)
     end
 
     return super
@@ -36,7 +36,7 @@ module RESTFramework::Mixins::BulkUpdateModelMixin
   def update_all
     records = self.update_all!
     serialized_records = self.bulk_serialize(records)
-    render_api(serialized_records)
+    render(api: serialized_records)
   end
 
   # Perform the `update` call and return the collection of (possibly) updated records.
@@ -62,11 +62,11 @@ module RESTFramework::Mixins::BulkDestroyModelMixin
     if params[:_json].is_a?(Array)
       records = self.destroy_all!
       serialized_records = self.bulk_serialize(records)
-      return render_api(serialized_records)
+      return render(api: serialized_records)
     end
 
-    render_api(
-      {message: "Bulk destroy requires an array of primary keys as input."},
+    render(
+      api: {message: "Bulk destroy requires an array of primary keys as input."},
       status: 400,
     )
   end

data/lib/rest_framework/mixins/model_controller_mixin.rb

@@ -339,6 +339,71 @@ module RESTFramework::Mixins::BaseModelControllerMixin
       return @openapi_schema
     end
 
+    def openapi_schema_name
+      return @openapi_schema_name ||= self.name.chomp("Controller").gsub("::", ".")
+    end
+
+    def openapi_paths(_routes, tag)
+      paths = super
+      schema_name = self.openapi_schema_name
+
+      # Reference the model schema for request body and successful default responses.
+      paths.each do |_path, actions|
+        actions.each do |method, action|
+          next unless action.is_a?(Hash)
+
+          extra_action = action.dig("x-rrf-metadata", :extra_action)
+
+          # Adjustments for builtin actions:
+          if !extra_action && method != "options"  # rubocop:disable Style/Next
+            # Add schema to request body content types.
+            action.dig(:requestBody, :content)&.each do |_t, v|
+              v[:schema] = {"$ref" => "#/components/schemas/#{schema_name}"}
+            end
+
+            # Add schema to successful response body content types.
+            action[:responses].each do |status, response|
+              next unless status.to_s.start_with?("2")
+
+              response[:content]&.each do |t, v|
+                next if t == "text/html"
+
+                v[:schema] = {"$ref" => "#/components/schemas/#{schema_name}"}
+              end
+            end
+
+            # Translate 200->201 for the create action.
+            if action[:summary] == "Create"
+              action[:responses][201] = action[:responses].delete(200)
+            end
+
+            # Translate 200->204 for the destroy action.
+            if action[:summary] == "Destroy"
+              action[:responses][204] = action[:responses].delete(200)
+            end
+          end
+        end
+      end
+
+      return paths
+    end
+
+    def openapi_document(request, route_group_name, _routes)
+      document = super
+
+      # Insert schema into the document.
+      document[:components] ||= {}
+      document[:components][:schemas] ||= {}
+      document[:components][:schemas][self.openapi_schema_name] = self.openapi_schema
+
+      return document.merge(
+        {
+          "x-rrf-primary_key" => self.get_model.primary_key,
+          "x-rrf-callbacks" => self._process_action_callbacks.as_json,
+        },
+      )
+    end
+
     def setup_delegation
       # Delegate extra actions.
       self.extra_actions&.each do |action, config|
@@ -349,9 +414,9 @@ module RESTFramework::Mixins::BaseModelControllerMixin
           model = self.class.get_model
 
           if model.method(action).parameters.last&.first == :keyrest
-            render_api(model.send(action, **params))
+            render(api: model.send(action, **params))
           else
-            render_api(model.send(action))
+            render(api: model.send(action))
           end
         end
       end
@@ -365,9 +430,9 @@ module RESTFramework::Mixins::BaseModelControllerMixin
           record = self.get_record
 
           if record.method(action).parameters.last&.first == :keyrest
-            render_api(record.send(action, **params))
+            render(api: record.send(action, **params))
           else
-            render_api(record.send(action))
+            render(api: record.send(action))
           end
         end
       end
@@ -409,40 +474,6 @@ module RESTFramework::Mixins::BaseModelControllerMixin
     return self.class.get_fields(input_fields: self.class.fields)
   end
 
-  def openapi_metadata
-    data = super
-    routes = self.route_groups.values[0]
-    schema_name = routes[0][:controller].camelize.gsub("::", ".")
-
-    # Insert schema into metadata.
-    data[:components] ||= {}
-    data[:components][:schemas] ||= {}
-    data[:components][:schemas][schema_name] = self.class.openapi_schema
-
-    # Reference schema for specific actions with a `requestBody`.
-    data[:paths].each do |_path, actions|
-      actions.each do |_method, action|
-        next unless action.is_a?(Hash)
-
-        injectables = [action.dig(:requestBody, :content), *action[:responses].values.map { |r|
-          r[:content]
-        }].compact
-        injectables.each do |i|
-          i.each do |_, v|
-            v[:schema] = {"$ref" => "#/components/schemas/#{schema_name}"}
-          end
-        end
-      end
-    end
-
-    return data.merge(
-      {
-        "x-rrf-primary_key" => self.class.get_model.primary_key,
-        "x-rrf-callbacks" => self._process_action_callbacks.as_json,
-      },
-    )
-  end
-
   # Get a hash of strong parameters for the current action.
   def get_allowed_parameters
     return @_get_allowed_parameters if defined?(@_get_allowed_parameters)
@@ -691,7 +722,7 @@ end
 # Mixin for listing records.
 module RESTFramework::Mixins::ListModelMixin
   def index
-    render_api(self.get_index_records)
+    render(api: self.get_index_records)
   end
 
   # Get records with both filtering and pagination applied.
@@ -719,14 +750,14 @@ end
 # Mixin for showing records.
 module RESTFramework::Mixins::ShowModelMixin
   def show
-    render_api(self.get_record)
+    render(api: self.get_record)
   end
 end
 
 # Mixin for creating records.
 module RESTFramework::Mixins::CreateModelMixin
   def create
-    render_api(self.create!, status: :created)
+    render(api: self.create!, status: :created)
   end
 
   # Perform the `create!` call and return the created record.
@@ -738,7 +769,7 @@ end
 # Mixin for updating records.
 module RESTFramework::Mixins::UpdateModelMixin
   def update
-    render_api(self.update!)
+    render(api: self.update!)
   end
 
   # Perform the `update!` call and return the updated record.
@@ -753,7 +784,7 @@ end
 module RESTFramework::Mixins::DestroyModelMixin
   def destroy
     self.destroy!
-    render_api("")
+    render(api: "")
   end
 
   # Perform the `destroy!` call and return the destroyed (and frozen) record.

data/lib/rest_framework/routers.rb

@@ -51,9 +51,16 @@ module ActionDispatch::Routing
       parsed_actions = RESTFramework::Utils.parse_extra_actions(actions)
 
       parsed_actions.each do |action, config|
-        [config[:methods]].flatten.each do |m|
-          public_send(m, config[:path], action: action, **(config[:kwargs] || {}))
+        config[:methods].each do |m|
+          public_send(m, config[:path], action: action, **config[:kwargs])
         end
+
+        # Record that this route is an extra action and any metadata associated with it.
+        metadata = config[:metadata]
+        key = "#{@scope[:path]}/#{config[:path]}"
+        RESTFramework::EXTRA_ACTION_ROUTES.add(key)
+        RESTFramework::ROUTE_METADATA[key] = metadata if metadata
+
         yield if block_given?
       end
     end

data/lib/rest_framework/utils.rb

@@ -1,49 +1,32 @@
 module RESTFramework::Utils
   HTTP_VERB_ORDERING = %w(GET POST PUT PATCH DELETE OPTIONS HEAD)
 
-  # Convert `extra_actions` hash to a consistent format: `{path:, methods:, kwargs:}`.
-  #
-  # If a controller is provided, labels will be added to any metadata fields.
-  def self.parse_extra_actions(extra_actions, controller: nil)
+  # Convert `extra_actions` hash to a consistent format: `{path:, methods:, metadata:, kwargs:}`.
+  def self.parse_extra_actions(extra_actions)
     return (extra_actions || {}).map { |k, v|
       path = k
+      kwargs = {}
 
       # Convert structure to path/methods/kwargs.
-      if v.is_a?(Hash)  # Allow kwargs to be used to define path differently from the key.
+      if v.is_a?(Hash)
         # Symbolize keys (which also makes a copy so we don't mutate the original).
         v = v.symbolize_keys
-        methods = v.delete(:methods)
-        if v.key?(:method)
-          methods = v.delete(:method)
-        end
 
-        # Add label to metadata fields, if any exist.
-        metadata = v[:metadata]
-        if controller && metadata&.key?(:fields)
-          metadata[:fields] = metadata[:fields].map { |f|
-            [f, {}]
-          }.to_h if metadata[:fields].is_a?(Array)
-          metadata[:fields]&.each do |field, cfg|
-            cfg[:label] = controller.label_for(field) unless cfg[:label]
-          end
-        end
+        # Cast method/methods to an array.
+        methods = [v.delete(:methods), v.delete(:method)].flatten.compact
 
         # Override path if it's provided.
         if v.key?(:path)
           path = v.delete(:path)
         end
 
+        # Extract metadata, if provided.
+        metadata = v.delete(:metadata).presence
+
         # Pass any further kwargs to the underlying Rails interface.
-        kwargs = v.presence
-      elsif v.is_a?(Array) && v.length == 1
-        methods = v[0]
+        kwargs = v
       else
-        methods = v
-      end
-
-      # Insert action label if it's not provided.
-      if controller
-        metadata[:label] ||= controller.label_for(k)
+        methods = [v].flatten
       end
 
       next [
@@ -51,6 +34,7 @@ module RESTFramework::Utils
         {
           path: path,
           methods: methods,
+          metadata: metadata,
           kwargs: kwargs,
         }.compact,
       ]
@@ -139,7 +123,9 @@ module RESTFramework::Utils
       ]
     }.group_by { |r| r[:controller] }.sort_by { |c, _r|
       # Sort the controller groups by current controller first, then alphanumerically.
-      [request.params[:controller] == c ? 0 : 1, c]
+      # Note: Use `controller_path` instead of `params[:controller]` to avoid re-raising a
+      # `ActionDispatch::Http::Parameters::ParseError` exception.
+      [request.controller_class.controller_path == c ? 0 : 1, c]
     }.to_h
   end
 

data/lib/rest_framework.rb

@@ -20,6 +20,10 @@ module RESTFramework
     destroy_all: :delete,
   }.freeze
 
+  # Storage for extra routes and associated metadata.
+  EXTRA_ACTION_ROUTES = Set.new
+  ROUTE_METADATA = {}
+
   # We put most vendored external assets into these files to make precompilation and serving faster.
   EXTERNAL_CSS_NAME = "rest_framework/external.min.css"
   EXTERNAL_JS_NAME = "rest_framework/external.min.js"
@@ -136,15 +140,18 @@ module RESTFramework
       authenticity_token
     ].freeze
 
-    # Do not run `rrf_finalize` on controllers automatically using a `TracePoint` hook. This is a
-    # performance option and must be global because we have to determine this before any
-    # controller-specific configuration is set. If this is set to `true`, then you must manually
-    # call `rrf_finalize` after any configuration on each controller that needs to participate
-    # in:
+    # Permits use of `render(api: obj)` syntax over `render_api(obj)`; `true` by default.
+    attr_accessor :register_api_renderer
+
+    # Run `rrf_finalize` on controllers automatically using a `TracePoint` hook. This is `true` by
+    # default, and can be disabled for performance, and must be global because we have to determine
+    # this before any controller-specific configuration is set. If this is set to `false`, then you
+    # must manually call `rrf_finalize` after any configuration on each controller that needs to
+    # participate in:
     #  - Model delegation, for the helper methods to be defined dynamically.
     #  - Websockets, for `::Channel` class to be defined dynamically.
     #  - Controller configuration freezing.
-    attr_accessor :disable_auto_finalize
+    attr_accessor :auto_finalize
 
     # Freeze configuration attributes during finalization to prevent accidental mutation.
     attr_accessor :freeze_config
@@ -173,7 +180,11 @@ module RESTFramework
     attr_accessor :use_vendored_assets
 
     def initialize
+      self.register_api_renderer = true
+      self.auto_finalize = true
+
       self.show_backtrace = Rails.env.development?
+
       self.label_fields = DEFAULT_LABEL_FIELDS
       self.search_columns = DEFAULT_SEARCH_COLUMNS
       self.exclude_body_fields = DEFAULT_EXCLUDE_BODY_FIELDS

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rest_framework
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta1
+  version: 1.0.0.rc1
 platform: ruby
 authors:
 - Gregory N. Schmit
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-25 00:00:00.000000000 Z
+date: 2025-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails