model_driven_api 3.6.3 → 3.6.4

data/lib/api/open_api/v3.rb

@@ -0,0 +1,349 @@
+module Api
+  module OpenApi
+    class V3 < Base
+      def generate
+        paths = {}
+        paths.merge!(v3_authenticate_path)
+        paths.merge!(v3_raw_sql_paths)
+        paths.merge!(v3_info_paths)
+        ApplicationRecord.subclasses.sort_by(&:to_s).each do |model_class|
+          paths.merge!(v3_crud_paths(model_class))
+          paths.merge!(v3_custom_action_paths(model_class))
+        end
+        paths
+      end
+
+      def description
+        v3_description
+      end
+
+      private
+
+      def v3_authenticate_path
+        {
+          "/authenticate" => {
+            "post" => {
+              "summary" => "Authenticate",
+              "tags" => ["Authentication"],
+              "description" => "Exchange email/password for a JWT. The token is returned in the `Token` response header.",
+              "requestBody" => {
+                "required" => true,
+                "content" => {
+                  "application/json" => {
+                    "schema" => {
+                      "type" => "object",
+                      "properties" => {
+                        "auth" => {
+                          "type" => "object",
+                          "properties" => {
+                            "email" => { "type" => "string", "format" => "email" },
+                            "password" => { "type" => "string", "format" => "password" },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+              "responses" => {
+                "200" => {
+                  "description" => "Authenticated — JWT in Token header",
+                  "headers" => { "Token" => { "description" => "JWT", "schema" => { "type" => "string" } } },
+                },
+                "401" => { "description" => "Unauthorized" },
+              },
+            },
+          },
+        }
+      end
+
+      def v3_raw_sql_paths
+        response_schema = {
+          "type" => "array",
+          "items" => { "type" => "object", "additionalProperties" => true },
+        }
+        query_param = {
+          "name" => "query",
+          "in" => "query",
+          "required" => true,
+          "schema" => { "type" => "string" },
+          "example" => "SELECT id, name FROM roles LIMIT 10",
+        }
+        body_schema = {
+          "type" => "object",
+          "properties" => { "query" => { "type" => "string" } },
+        }
+        {
+          "/raw/sql" => {
+            "get" => {
+              "summary" => "Raw SQL (GET)",
+              "tags" => ["Raw"],
+              "description" => "Execute a SELECT query. Returns rows as a plain JSON array (not JSON:API).",
+              "security" => [{ "bearerAuth" => [] }],
+              "parameters" => [query_param],
+              "responses" => {
+                "200" => { "description" => "Rows", "content" => { "application/json" => { "schema" => response_schema } } },
+                "400" => { "description" => "Only SELECT statements are allowed" },
+              },
+            },
+            "post" => {
+              "summary" => "Raw SQL (POST)",
+              "tags" => ["Raw"],
+              "description" => "Execute a SELECT query. Returns rows as a plain JSON array (not JSON:API).",
+              "security" => [{ "bearerAuth" => [] }],
+              "requestBody" => { "required" => true, "content" => { "application/json" => { "schema" => body_schema } } },
+              "responses" => {
+                "200" => { "description" => "Rows", "content" => { "application/json" => { "schema" => response_schema } } },
+                "400" => { "description" => "Only SELECT statements are allowed" },
+              },
+            },
+          },
+        }
+      end
+
+      def v3_info_paths
+        {
+          "/info/version" => {
+            "get" => {
+              "summary" => "Version", "tags" => ["Info"],
+              "responses" => { "200" => { "description" => "App version string" } },
+            },
+          },
+          "/info/heartbeat" => {
+            "get" => {
+              "summary" => "Heartbeat", "tags" => ["Info"],
+              "security" => [{ "bearerAuth" => [] }],
+              "responses" => { "200" => { "description" => "Renews token, returns current user as plain JSON" } },
+            },
+          },
+          "/info/roles" => {
+            "get" => {
+              "summary" => "Roles", "tags" => ["Info"],
+              "security" => [{ "bearerAuth" => [] }],
+              "responses" => { "200" => { "description" => "All roles as plain JSON array" } },
+            },
+          },
+          "/info/schema" => {
+            "get" => {
+              "summary" => "Schema", "tags" => ["Info"],
+              "security" => [{ "bearerAuth" => [] }],
+              "responses" => { "200" => { "description" => "DB schema for models the user can read" } },
+            },
+          },
+          "/info/dsl" => {
+            "get" => {
+              "summary" => "DSL", "tags" => ["Info"],
+              "security" => [{ "bearerAuth" => [] }],
+              "responses" => { "200" => { "description" => "json_attrs DSL for each model" } },
+            },
+          },
+          "/info/translations" => {
+            "get" => {
+              "summary" => "Translations", "tags" => ["Info"],
+              "security" => [{ "bearerAuth" => [] }],
+              "parameters" => [{ "name" => "locale", "in" => "query", "schema" => { "type" => "string" } }],
+              "responses" => { "200" => { "description" => "Full i18n translation tree" } },
+            },
+          },
+          "/info/settings" => {
+            "get" => {
+              "summary" => "Settings", "tags" => ["Info"],
+              "security" => [{ "bearerAuth" => [] }],
+              "responses" => { "200" => { "description" => "All ThecoreSettings::Setting values" } },
+            },
+          },
+          "/info/swagger" => {
+            "get" => {
+              "summary" => "OpenAPI v3 spec", "tags" => ["Info"],
+              "responses" => { "200" => { "description" => "This OpenAPI 3.0 specification" } },
+            },
+          },
+        }
+      end
+
+      def v3_crud_paths(model_class)
+        resource_type = model_class.model_name.plural
+        tag = model_class.model_name.name
+
+        attrs = begin
+          props = create_properties_from_model(model_class, model_class.json_attrs || {})
+          props.reject { |k, _| k.to_s == "id" }
+        rescue
+          {}
+        end
+
+        writable_attrs = begin
+          create_properties_from_model(model_class, {}, true)
+        rescue
+          {}
+        end
+
+        resource_schema = {
+          "type" => "object",
+          "properties" => {
+            "id" => { "type" => "string" },
+            "type" => { "type" => "string", "example" => resource_type },
+            "attributes" => { "type" => "object", "properties" => attrs },
+          },
+        }
+        collection_schema = {
+          "type" => "object",
+          "properties" => {
+            "data" => { "type" => "array", "items" => resource_schema },
+            "meta" => { "type" => "object", "properties" => { "total" => { "type" => "integer" } } },
+          },
+        }
+        single_schema = { "type" => "object", "properties" => { "data" => resource_schema } }
+        request_schema = {
+          "type" => "object",
+          "properties" => {
+            "data" => {
+              "type" => "object",
+              "properties" => {
+                "type" => { "type" => "string", "example" => resource_type },
+                "attributes" => { "type" => "object", "properties" => writable_attrs },
+              },
+            },
+          },
+        }
+
+        filter_params = begin
+          model_class.ransackable_attributes.map do |attr|
+            { "name" => "filter[#{attr}]", "in" => "query", "schema" => { "type" => "string" } }
+          end
+        rescue
+          []
+        end
+
+        id_param = { "name" => "id", "in" => "path", "required" => true, "schema" => { "type" => "integer" } }
+        sort_param = { "name" => "sort", "in" => "query", "schema" => { "type" => "string" }, "description" => "field or -field (descending), comma-separated" }
+        page_params = [
+          { "name" => "page[number]", "in" => "query", "schema" => { "type" => "integer" } },
+          { "name" => "page[size]",   "in" => "query", "schema" => { "type" => "integer" } },
+        ]
+        include_param  = { "name" => "include", "in" => "query", "schema" => { "type" => "string" }, "description" => "Associations to sideload (empty to suppress defaults)" }
+        fields_param   = { "name" => "fields[#{resource_type}]", "in" => "query", "schema" => { "type" => "string" }, "description" => "Sparse fieldsets" }
+
+        vnd = "application/vnd.api+json"
+
+        {
+          "/#{resource_type}" => {
+            "get" => {
+              "summary" => "Index #{tag}",
+              "tags" => [tag],
+              "security" => [{ "bearerAuth" => [] }],
+              "parameters" => [*page_params, *filter_params, sort_param, include_param, fields_param],
+              "responses" => {
+                "200" => { "description" => "Collection", "content" => { vnd => { "schema" => collection_schema } } },
+              },
+            },
+            "post" => {
+              "summary" => "Create #{tag}",
+              "tags" => [tag],
+              "security" => [{ "bearerAuth" => [] }],
+              "requestBody" => { "required" => true, "content" => { vnd => { "schema" => request_schema } } },
+              "responses" => {
+                "201" => { "description" => "Created", "content" => { vnd => { "schema" => single_schema } } },
+              },
+            },
+          },
+          "/#{resource_type}/{id}" => {
+            "get" => {
+              "summary" => "Show #{tag}",
+              "tags" => [tag],
+              "security" => [{ "bearerAuth" => [] }],
+              "parameters" => [id_param, include_param, fields_param],
+              "responses" => {
+                "200" => { "description" => "Resource", "content" => { vnd => { "schema" => single_schema } } },
+                "404" => { "description" => "Not found" },
+              },
+            },
+            "patch" => {
+              "summary" => "Update #{tag}",
+              "tags" => [tag],
+              "security" => [{ "bearerAuth" => [] }],
+              "parameters" => [id_param],
+              "requestBody" => { "required" => true, "content" => { vnd => { "schema" => request_schema } } },
+              "responses" => {
+                "200" => { "description" => "Updated", "content" => { vnd => { "schema" => single_schema } } },
+                "404" => { "description" => "Not found" },
+              },
+            },
+            "delete" => {
+              "summary" => "Destroy #{tag}",
+              "tags" => [tag],
+              "security" => [{ "bearerAuth" => [] }],
+              "parameters" => [id_param],
+              "responses" => {
+                "204" => { "description" => "No Content" },
+                "404" => { "description" => "Not found" },
+              },
+            },
+          },
+        }
+      end
+
+      def v3_custom_action_paths(model_class)
+        paths = {}
+        resource_type = model_class.model_name.plural
+        tag = model_class.model_name.name
+        custom_actions = ("Endpoints::#{tag}".constantize.instance_methods(false) rescue [])
+        custom_actions.each do |action|
+          definition = ("Endpoints::#{tag}".constantize.definitions[tag][action.to_sym] rescue nil)
+          next unless definition
+          definition.each { |_verb, spec| spec[:tags] = [tag] if spec.is_a?(Hash) }
+          has_id = definition.any? { |_v, spec| spec.is_a?(Hash) && spec[:parameters]&.any? { |p| p[:in] == "path" } }
+          path = "/#{resource_type}/custom_action/#{action}#{has_id ? "/{id}" : ""}"
+          paths[path] = definition
+        end
+        paths
+      end
+
+      def v3_description
+        <<~MD
+          ## API v3 — JSON:API
+
+          All resource endpoints follow the [JSON:API 1.0](https://jsonapi.org) specification.
+
+          ### Authentication
+
+          `POST /authenticate` → JWT in `Token` response header. Pass as `Authorization: Bearer <token>`.
+          Every successful request renews the token — always read and store the new `Token` header.
+
+          ### Content negotiation
+
+          `Accept: application/vnd.api+json` (GET) · `Content-Type: application/vnd.api+json` (write requests).
+
+          ### Filtering
+
+          `?filter[field]=value` — validated against each model's `ransackable_attributes`.
+
+          ### Sorting
+
+          `?sort=field` (asc) · `?sort=-field` (desc) · `?sort=field1,-field2` (multi-field).
+
+          ### Pagination
+
+          `?page[number]=N&page[size]=N` — response includes `meta.total`.
+
+          ### Sparse fieldsets
+
+          `?fields[type]=field1,field2` — restrict attributes returned per resource type.
+
+          ### Sideloading
+
+          Default sideloads come from each model's `json_attrs[:include]`.
+          Override with `?include=assoc1,assoc2` · suppress all with `?include=` (empty string).
+
+          ### Info & utility endpoints
+
+          `GET /info/version|heartbeat|roles|schema|dsl|translations|settings|swagger` — return plain JSON (not JSON:API).
+
+          ### Raw SQL escape hatch
+
+          `GET|POST /raw/sql` — SELECT-only; returns plain JSON array (not JSON:API).
+        MD
+      end
+    end
+  end
+end

data/lib/api/resource_attribute_set.rb

@@ -0,0 +1,25 @@
+module Api
+  ResourceAttributeSet = Struct.new(:attributes, :methods_list, :includes) do
+    def self.for(model_class, jattrs: nil)
+      jattrs ||= model_class.respond_to?(:json_attrs) ? (model_class.json_attrs || {}) : {}
+      only = Array(jattrs[:only]).map(&:to_sym)
+      if only.empty?
+        except = Array(jattrs[:except]).map(&:to_sym)
+        only = model_class.column_names.map(&:to_sym) - except
+      end
+      new(only.reject { |a| a == :id }, Array(jattrs[:methods]).map(&:to_sym), jattrs[:include])
+    end
+
+    # Parse json_attrs[:include] into { assoc_name => spec_or_nil }.
+    # Handles both symbol items (:roles) and hash items (users: { only: [:id] }).
+    def parsed_includes
+      return {} unless includes
+      Array(includes).each_with_object({}) do |item, hash|
+        case item
+        when Hash then item.each { |k, v| hash[k] = v }
+        when Symbol then hash[item] = nil
+        end
+      end
+    end
+  end
+end

data/lib/api/v3/serializer_factory.rb

@@ -0,0 +1,65 @@
+module Api
+  module V3
+    class SerializerFactory
+      # Generate (and cache) a JSONAPI::Serializer subclass for model_class.
+      #
+      # nested_attrs: when set, use these attrs instead of model_class.json_attrs.
+      #   Used for included associations — avoids reading the associated model's own
+      #   json_attrs and prevents infinite recursion.
+      # parent_name: when set, the generated constant is named
+      #   "#{model_class.name}For#{parent_name}Serializer" and include: is NOT
+      #   processed (one level deep only).
+      def self.serializer_for(model_class, nested_attrs: nil, parent_name: nil)
+        const_name = parent_name ? "#{model_class.name}For#{parent_name}Serializer" : "#{model_class.name}Serializer"
+        return Api::V3.const_get(const_name) if Api::V3.const_defined?(const_name)
+
+        jattrs = nested_attrs || (model_class.respond_to?(:json_attrs) ? (model_class.json_attrs || {}) : {})
+        attr_set = Api::ResourceAttributeSet.for(model_class, jattrs: jattrs)
+
+        # Nested serializers are always flat — no recursive includes — to prevent
+        # infinite loops on circular associations (e.g. Role↔User).
+        includes_map = parent_name ? {} : attr_set.parsed_includes
+
+        type = model_class.model_name.plural.to_sym
+
+        reflections = model_class.reflect_on_all_associations.each_with_object({}) { |r, h| h[r.name] = r }
+        nested_info = includes_map.each_with_object({}) do |(assoc_name, assoc_spec), hash|
+          reflection = reflections[assoc_name]
+          next unless reflection
+          nested_ser = assoc_spec \
+            ? serializer_for(reflection.klass, nested_attrs: assoc_spec, parent_name: model_class.name) \
+            : serializer_for(reflection.klass)
+          hash[assoc_name] = { serializer: nested_ser, macro: reflection.macro }
+        end
+
+        klass = Class.new do
+          include JSONAPI::Serializer
+          set_type type
+          attributes(*attr_set.attributes) if attr_set.attributes.any?
+
+          attr_set.methods_list.each do |method_name|
+            attribute(method_name) { |object| object.send(method_name) }
+          end
+
+          nested_info.each do |assoc_name, info|
+            ser = info[:serializer]
+            case info[:macro]
+            when :has_many   then has_many   assoc_name, serializer: ser
+            when :has_one    then has_one    assoc_name, serializer: ser
+            when :belongs_to then belongs_to assoc_name, serializer: ser
+            end
+          end
+        end
+
+        Api::V3.const_set(const_name, klass)
+        klass
+      end
+
+      # Parse json_attrs[:include] into { assoc_name => spec_or_nil }.
+      # Delegates to Api::ResourceAttributeSet#parsed_includes.
+      def self.extract_includes(include_spec)
+        Api::ResourceAttributeSet.new([], [], include_spec).parsed_includes
+      end
+    end
+  end
+end

data/lib/model_driven_api/engine.rb

@@ -1,8 +1,14 @@
 module ModelDrivenApi
   class Engine < ::Rails::Engine
     # appending migrations to the main app's ones
+    initializer :register_json_api_mime_type do
+      Mime::Type.register "application/vnd.api+json", :json_api unless Mime[:json_api]
+      ActionDispatch::Request.parameter_parsers[:json_api] =
+        ActionDispatch::Request.parameter_parsers[:json]
+    end
+
     initializer :append_migrations do |app|
-      unless app.root.to_s.match root.to_s
+      unless app.root.to_s == root.to_s
         config.paths["db/migrate"].expanded.each do |expanded_path|
           app.config.paths["db/migrate"] << expanded_path
         end

data/lib/model_driven_api/version.rb

@@ -1,3 +1,3 @@
 module ModelDrivenApi
-  VERSION = "3.6.3".freeze
+  VERSION = "3.6.4".freeze
 end

data/lib/model_driven_api.rb

@@ -6,6 +6,7 @@ require 'ransack'
 require 'jwt'
 require 'json_web_token'
 require "kaminari"
+require "pagy"
 # require "multi_json"
 require "simple_command"
 
@@ -16,6 +17,13 @@ require 'deep_merge/rails_compat'
 require "model_driven_api/engine"
 
 require "safe_sql_executor"
+require "api/resource_attribute_set"
+require "api/model_resolver"
+require "api/custom_action_dispatcher"
+require "api/open_api/base"
+require "api/open_api/v2"
+require "api/open_api/v3"
+require "api/v3/serializer_factory"
 
 module ModelDrivenApi
   def self.smart_merge src, dest

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: model_driven_api
 version: !ruby/object:Gem::Version
-  version: 3.6.3
+  version: 3.6.4
 platform: ruby
 authors:
 - Gabriele Tassoni
@@ -94,19 +94,75 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.2'
 - !ruby/object:Gem::Dependency
-  name: sqlite3
+  name: jsonapi-serializer
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: pagy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: factory_bot_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '6.4'
 description: Ruby on Rails REST APIs built by convention using the DB schema as the
   foundation, please see README for mode of use.
 email:
@@ -126,6 +182,12 @@ files:
 - app/controllers/api/v2/info_controller.rb
 - app/controllers/api/v2/raw_controller.rb
 - app/controllers/api/v2/users_controller.rb
+- app/controllers/api/v3/application_controller.rb
+- app/controllers/api/v3/auth/oauth_controller.rb
+- app/controllers/api/v3/authentication_controller.rb
+- app/controllers/api/v3/info_controller.rb
+- app/controllers/api/v3/raw_controller.rb
+- app/controllers/api/v3/users_controller.rb
 - app/models/endpoints/test_api.rb
 - app/models/test_api.rb
 - app/models/used_token.rb
@@ -138,6 +200,13 @@ files:
 - config/routes.rb
 - db/migrate/20210519145438_create_used_tokens.rb
 - db/migrate/20210528111450_rename_valid_to_is_valid_in_used_token.rb
+- lib/api/custom_action_dispatcher.rb
+- lib/api/model_resolver.rb
+- lib/api/open_api/base.rb
+- lib/api/open_api/v2.rb
+- lib/api/open_api/v3.rb
+- lib/api/resource_attribute_set.rb
+- lib/api/v3/serializer_factory.rb
 - lib/concerns/api_exception_management.rb
 - lib/concerns/model_driven_api_application_record.rb
 - lib/concerns/model_driven_api_role.rb