model_driven_api 3.6.3 → 3.6.4

data/lib/api/open_api/v2.rb

@@ -0,0 +1,1238 @@
+module Api
+  module OpenApi
+    class V2 < Base
+      def generate
+        pivot = {
+          "/authenticate": {
+            "post": {
+              "summary": "Authenticate",
+              "tags": ["Authentication"],
+              "description": "Authenticate the user and return a JWT token in the header and the current user as body.",
+              "security": [
+                "basicAuth": [],
+              ],
+              "requestBody": {
+                "content": {
+                  "application/json": {
+                    "schema": {
+                      "type": "object",
+                      "properties": {
+                        "auth": {
+                          "type": "object",
+                          "properties": {
+                            "email": {
+                              "type": "string",
+                              "format": "email",
+                            },
+                            "password": {
+                              "type": "string",
+                              "format": "password",
+                            },
+                          },
+                        },
+                      },
+                      "required": ["email", "password"],
+                    },
+                  },
+                },
+              },
+              "responses": {
+                "200": {
+                  "description": "User authenticated",
+                  "headers": {
+                    "token": {
+                      "description": "JWT",
+                      "schema": {
+                        "type": "string",
+                      },
+                    },
+                  },
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "object",
+                        # ["id", "email", "created_at", "admin", "locked", "supplier_id", "location_id", "roles"]
+                        "properties": create_properties_from_model(User, User.json_attrs),
+                      },
+                    },
+                  },
+                },
+                "401": {
+                  "description": "Unauthorized",
+                },
+              },
+            },
+          },
+          "/raw/sql": {
+            "post": {
+              "summary": "Raw SQL query execution of SELECT queries",
+              "description": "Executes a SQL query on the underlying PostgreSQL database, the query must return the JSON in a **result** key (please note in the examples the _SELECT json_agg(u) AS result_ or in the more complex one the _SELECT jsonb_agg(pick_data) AS result_, they always use the **result** return object).\n \nDesigned for SELECT queries that use the json_agg function to aggregate results into JSON arrays, which must return the JSON in a **result** key.\n \nOther query types are not recommended and may be restricted for security and performance reasons.\n \nOnly SELECT statements are allowed. DDL and DML statements (INSERT, UPDATE, DELETE) are forbidden.\n \nQueries can be as simple as:\n \n```sql\nSELECT json_agg(u) AS result\nFROM users u\nWHERE u.active = true;\n```\n \nor more complex, using joins, subqueries, CTEs, and other SQL features. like:\n \n```sql\nWITH pick_data AS (\n   SELECT p.id,\n      p.project_id,\n      p.quantity,\n      p.created_at,\n      p.updated_at,\n      p.notes,\n      p.document_id,\n      p.external_code,\n      p.reference_project_id,\n      p.reference_row,\n      p.closed,\n      p.parent_reference_row,\n      p.packages,\n      p.weight,\n      p.dispatched_quantity,\n      p.override_item_reference,\n      p.override_item_description,\n      p.override_item_measure_unit,\n      p.lock_version,\n      p.user_id,\n      COALESCE(SUM(pr.quantity), 0) AS quantity_detected,\n      COALESCE(p.quantity, 0) - COALESCE(SUM(pr.quantity), 0) AS quantity_remaining,\n      json_agg(\n         jsonb_build_object(\n            'id',\n            pr.id,\n            'item_id',\n            pr.item_id,\n            'location_id',\n            pr.location_id,\n            'quantity',\n            pr.quantity\n         )\n      ) AS project_rows,\n      jsonb_build_object(\n         'id',\n         l.id,\n         'name',\n         l.name,\n         'description',\n         l.description\n      ) AS location,\n      jsonb_build_object(\n         'id',\n         i.id,\n         'code',\n         i.code,\n         'created_at',\n         i.created_at,\n         'updated_at',\n         i.updated_at,\n         'description',\n         i.description,\n         'has_serials',\n         i.has_serials,\n         'external_code',\n         i.external_code,\n         'barcode',\n         i.barcode,\n         'weight',\n         i.weight,\n         'quantity',\n         i.quantity,\n         'package_quantity',\n         i.package_quantity,\n         'locked_quantity',\n         i.locked_quantity,\n         'disabled',\n         i.disabled,\n         'measure_unit',\n         jsonb_build_object('id', mu.id, 'name', mu.name),\n         'location',\n         jsonb_build_object('id', il.id, 'name', il.name),\n         'locations',\n         (\n            SELECT jsonb_agg(\n                  jsonb_build_object('id', loc.id, 'name', loc.name)\n               )\n            FROM locations loc\n               JOIN item_locations il ON il.location_id = loc.id\n            WHERE il.item_id = i.id\n         ),\n         'additional_barcodes',\n         (\n            SELECT jsonb_agg(\n                  jsonb_build_object('id', ab.id, 'code', ab.code)\n               )\n            FROM additional_barcodes ab\n            WHERE ab.item_id = i.id\n         )\n      ) AS item\n   FROM picks p\n      LEFT JOIN project_rows pr ON pr.pick_id = p.id\n      LEFT JOIN locations l ON l.id = p.location_id\n      LEFT JOIN items i ON i.id = p.item_id\n      LEFT JOIN measure_units mu ON mu.id = i.measure_unit_id\n      LEFT JOIN locations il ON il.id = i.location_id\n   WHERE p.project_id = 16130\n   GROUP BY p.id,\n      l.id,\n      i.id,\n      mu.id,\n      il.id\n)\nSELECT jsonb_agg(pick_data) AS result\nFROM pick_data;\n```\n \nLet's break down the provided SQL query and understand why it uses a Common Table Expression (CTE) and how it can improve performance.\n \n### Explanation of the complex Query\n \nThe provided query uses a CTE named `pick_data` to gather and aggregate data from multiple tables (`picks`, `project_rows`, `locations`, `items`, `measure_units`, `item_locations`, and `additional_barcodes`). The final result is a JSON array of aggregated data.\n \n#### Key Components of the Query:\n \n1. **CTE Definition**:\n \n   ```sql\n   WITH pick_data AS (\n     -- Subquery content\n   )\n   ```\n \n   The CTE `pick_data` is defined to encapsulate the logic of the subquery. This makes the query more readable and modular.\n \n2. **Data Selection and Aggregation**:\n   Inside the CTE, data is selected and aggregated from various tables. Key operations include:\n \n   - **Column Selection**: Selecting specific columns from the `picks` table.\n   - **Aggregation**: Using `COALESCE` and `SUM` to calculate `quantity_detected` and `quantity_remaining`.\n   - **JSON Aggregation**: Using `json_agg` and `jsonb_build_object` to create JSON objects and arrays for nested data structures.\n \n3. **Final Selection**:\n   ```sql\n   SELECT jsonb_agg(pick_data) AS result FROM pick_data;\n   ```\n   The final selection aggregates all rows from the CTE `pick_data` into a single JSON array.\n \n### Why Use a CTE?\n \n1. **Readability and Maintainability**:\n \n   - **Modular Code**: By using a CTE, the complex logic is encapsulated in a named subquery, making the main query easier to read and understand.\n   - **Reusability**: The CTE can be reused within the same query if needed, avoiding duplication of code.\n \n2. **Performance**:\n   - **Optimization**: Modern SQL engines can optimize CTEs effectively. They can be materialized (computed once and stored) or inlined (expanded in the main query) based on the query plan.\n   - **Intermediate Results**: CTEs allow breaking down complex queries into simpler steps, which can sometimes help the SQL engine optimize each step more effectively.\n \n### Documentation for Editing Generic Queries\n \nWhen editing or creating new queries, consider the following steps and best practices:\n \n1. **Identify the Purpose**:\n \n   - Clearly define what the query needs to achieve. Understand the data relationships and the final output format.\n \n2. **Use CTEs for Complex Logic**:\n \n   - Break down complex queries into smaller, manageable parts using CTEs. This improves readability and maintainability.\n \n3. **Optimize Aggregations and Joins**:\n \n   - Ensure that aggregations and joins are optimized. Use indexes where appropriate and avoid unnecessary computations.\n \n4. **Leverage JSON Functions**:\n \n   - Use JSON functions (`json_agg`, `jsonb_build_object`, etc.) to handle nested data structures effectively.\n \n5. **Test and Validate**:\n   - Test the query with different datasets to ensure it performs well and returns the correct results. Validate the output format.\n \n### Example of a Generic Query Using CTE\n \nHere's a generic example to illustrate how to use a CTE in a query:\n \n```sql\n \n\nWITH data_aggregation AS (\n  SELECT\n    t1.id,\n    t1.name,\n    SUM(t2.value) AS total_value,\n    json_agg(\n      jsonb_build_object(\n        'id', t2.id,\n        'value', t2.value\n      )\n    ) AS details\n  FROM table1 t1\n  LEFT JOIN table2 t2 ON t2.table1_id = t1.id\n  GROUP BY t1.id\n)\nSELECT jsonb_agg(data_aggregation) AS result FROM data_aggregation;\n```\n \n### Conclusion\n \nUsing CTEs in SQL queries helps in organizing complex logic, improving readability, and potentially enhancing performance. When editing or creating new queries, follow best practices such as breaking down complex logic, optimizing joins and aggregations, and leveraging JSON functions for nested data structures.\n",
+              "tags": ["Raw"],
+              "security": [
+                "bearerAuth": [],
+              ],
+              "responses": {
+                "200": {
+                  "description": "SQL Query Result",
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "properties": {
+                            "json_agg": {
+                              "type": "string",
+                            },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+                "400": {
+                  "description": "SQL query must return a key called result otherwise cannot be parsed",
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "object",
+                        "properties": {
+                          "error": {
+                            "type": "string",
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+
+              },
+              "requestBody": {
+                "content": {
+                  "application/json": {
+                    "schema": {
+                      "type": "object",
+                      "properties": {
+                        "query": {
+                          "type": "string",
+                          "example": "SELECT json_agg(u) FROM users u WHERE u.active = true;",
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "/info/version": {
+            "get": {
+              "summary": "Version",
+              "description": "Just prints the APPVERSION",
+              "tags": ["Info"],
+              "responses": {
+                "200": {
+                  "description": "APPVERSION",
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "string",
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "/info/heartbeat": {
+            "get": {
+              "summary": "Heartbeat",
+              "description": "Just keeps the session alive by returning a new token",
+              "tags": ["Info"],
+              "security": [
+                "bearerAuth": [],
+              ],
+              "responses": {
+                "200": {
+                  "description": "Session alive",
+                  "headers": {
+                    "token": {
+                      "description": "JWT",
+                      "schema": {
+                        "type": "string",
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "/info/roles": {
+            "get": {
+              "summary": "Roles",
+              "description": "Returns the roles list",
+              "tags": ["Info"],
+              "security": [
+                "bearerAuth": [],
+              ],
+              "responses": {
+                "200": {
+                  "description": "Roles list",
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "properties": {
+                            "id": {
+                              "type": "integer",
+                            },
+                            "name": {
+                              "type": "string",
+                            },
+                            "description": {
+                              "type": "string",
+                            },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "/info/schema": {
+            "get": {
+              "summary": "Schema",
+              "description": "Returns the schema of the models",
+              "tags": ["Info"],
+              "security": [
+                "bearerAuth": [],
+              ],
+              "responses": {
+                "200": {
+                  "description": "Schema of the models",
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "properties": {
+                            "id": {
+                              "type": "integer",
+                            },
+                            "created_at": {
+                              "type": "string",
+                              "format": "date-time",
+                            },
+                            "updated_at": {
+                              "type": "string",
+                              "format": "date-time",
+                            },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "/info/dsl": {
+            "get": {
+              "summary": "DSL",
+              "description": "Returns the DSL of the models",
+              "tags": ["Info"],
+              "security": [
+                "bearerAuth": [],
+              ],
+              "responses": {
+                "200": {
+                  "description": "DSL of the models",
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "integer",
+                          },
+                          "created_at": {
+                            "type": "string",
+                            "format": "date-time",
+                          },
+                          "updated_at": {
+                            "type": "string",
+                            "format": "date-time",
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "/info/translations": {
+            "get": {
+              "summary": "Translations",
+              "description": "Returns the translations of the entire App",
+              "tags": ["Info"],
+              "security": [
+                "bearerAuth": [],
+              ],
+              "responses": {
+                "200": {
+                  "description": "Translations",
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "object",
+                        "properties": {
+                          "key": {
+                            "type": "string",
+                          },
+                          "value": {
+                            "type": "string",
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "/info/settings": {
+            "get": {
+              "summary": "Settings",
+              "description": "Returns the settings of the App",
+              "tags": ["Info"],
+              "security": [
+                "bearerAuth": [],
+              ],
+              "responses": {
+                "200": {
+                  "description": "Settings",
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "object",
+                        "properties": {
+                          "ns": {
+                            "type": "object",
+                            "properties": {
+                              "key": {
+                                "type": "string",
+                              },
+                              "value": {
+                                "type": "string",
+                              },
+                            },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          "/info/swagger": {
+            "get": {
+              "summary": "Swagger",
+              "description": "Returns the self generated Swagger for all the models in the App.",
+              "tags": ["Info"],
+              "responses": {
+                "200": {
+                  "description": "Swagger",
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "integer",
+                          },
+                          "created_at": {
+                            "type": "string",
+                            "format": "date-time",
+                          },
+                          "updated_at": {
+                            "type": "string",
+                            "format": "date-time",
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        }
+        ApplicationRecord.subclasses.sort_by { |d| d.to_s }.each do |d|
+          # Only if current user can read the model
+          if true # can? :read, d
+            model = d.to_s.underscore.tableize
+            # CRUD and Search endpoints
+            pivot["/#{model}"] = {
+              "get": {
+                "summary": "Index",
+                "description": "Returns the list of #{model}",
+                "tags": [model.classify],
+                "security": [
+                  "bearerAuth": [],
+                ],
+                "responses": {
+                  "200": {
+                    "description": "List of #{model}",
+                    "content": {
+                      "application/json": {
+                        "schema": {
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": create_properties_from_model(d, (d.json_attrs rescue {})),
+                          },
+                        },
+                      },
+                    },
+                  },
+                  "404": {
+                    "description": "No #{model} found",
+                  },
+                },
+              },
+              "post": {
+                "summary": "Create",
+                "description": "Creates a new #{model}",
+                "tags": [model.classify],
+                "security": [
+                  "bearerAuth": [],
+                ],
+                "requestBody": {
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "object",
+                        "properties": {
+                          "#{model.singularize}": {
+                            "type": "object",
+                            "properties": create_properties_from_model(d, {}, true),
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+                "responses": {
+                  "200": {
+                    "description": "#{model} Created",
+                    "content": {
+                      "application/json": {
+                        "schema": {
+                          "type": "object",
+                          "properties": create_properties_from_model(d, (d.json_attrs rescue {})),
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            }
+            # Non CRUD or Search, but custom, usually bulk operations endpoints
+            new_custom_actions = ("Endpoints::#{d.model_name.name}".constantize.instance_methods(false) rescue [])
+            Rails.logger.debug "New Custom Actions (#{d.model_name.name}): #{new_custom_actions}"
+            new_custom_actions.each do |action|
+              openapi_definition = "Endpoints::#{d.model_name.name}".constantize.definitions[d.model_name.name][action.to_sym] rescue []
+
+              # Add the tag to the openapi definition
+              openapi_definition.each do |k, v|
+                v[:tags] = [d.model_name.name]
+              end
+
+              # Check if any HTTP method has path parameters with 'in: path', and if so, add {id} to the path
+              path = "/#{model}/custom_action/#{action}"
+              has_path_params = openapi_definition.any? { |_k, v| v.is_a?(Hash) && v[:parameters]&.any? { |p| p[:in] == 'path' } }
+              path += "/{id}" if has_path_params
+
+              pivot[path] = openapi_definition if openapi_definition
+            end
+            pivot["/#{model}/search"] = {
+              # Complex queries are made using ranskac search via a post endpoint
+              "post": {
+                "summary": "Search",
+                "description": "Searches the #{model} using complex queries. Please refer to the [documentation](https://activerecord-hackery.github.io/ransack/) for the query syntax and to the general description of this swagger document to discover the usage of other, non ransack predicates for example to count records, select only some fields and more.",
+                "tags": [model.classify],
+                "security": [
+                  "bearerAuth": [],
+                ],
+                "requestBody": {
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "object",
+                        "properties": {
+                          "q": {
+                            "type": "object",
+                            "properties": {
+                              "name_or_description_cont": {
+                                "type": "string",
+                              },
+                              "first_name_eq": {
+                                "type": "string",
+                              },
+                            },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+                "responses": {
+                  "200": {
+                    "description": "List of #{model}",
+                    "content": {
+                      "application/json": {
+                        "schema": {
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": create_properties_from_model(d, (d.json_attrs rescue {})),
+                          },
+                        },
+                      },
+                    },
+                  },
+                  "404": {
+                    "description": "No #{model} found",
+                  },
+                },
+              },
+            }
+            pivot["/#{model}/{id}"] = {
+              "put": {
+                "summary": "Update",
+                "description": "Updates the complete #{model}",
+                "parameters": [
+                  {
+                    "name": "id",
+                    "in": "path",
+                    "required": true,
+                    "schema": {
+                      "type": "integer",
+                    },
+                  },
+                ],
+                "tags": [model.classify],
+                "security": [
+                  "bearerAuth": [],
+                ],
+                "requestBody": {
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "object",
+                        "properties": {
+                          "#{model.singularize}": {
+                            "type": "object",
+                            "properties": create_properties_from_model(d, {}, true),
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+                "responses": {
+                  "200": {
+                    "description": "#{model} Updated",
+                    "content": {
+                      "application/json": {
+                        "schema": {
+                          "type": "object",
+                          "properties": create_properties_from_model(d, (d.json_attrs rescue {})),
+                        },
+                      },
+                    },
+                  },
+                  "404": {
+                    "description": "No #{model} found",
+                  },
+                },
+              },
+              "patch": {
+                "summary": "Patch",
+                "description": "Updates the partial #{model}",
+                "parameters": [
+                  {
+                    "name": "id",
+                    "in": "path",
+                    "required": true,
+                    "schema": {
+                      "type": "integer",
+                    },
+                  },
+                ],
+                "tags": [model.classify],
+                "security": [
+                  "bearerAuth": [],
+                ],
+                "requestBody": {
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "object",
+                        "properties": {
+                          "#{model.singularize}": {
+                            "type": "object",
+                            "properties": create_properties_from_model(d, {}, true),
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+                "responses": {
+                  "200": {
+                    "description": "#{model} Patched",
+                    "content": {
+                      "application/json": {
+                        "schema": {
+                          "type": "object",
+                          "properties": create_properties_from_model(d, (d.json_attrs rescue {})),
+                        },
+                      },
+                    },
+                  },
+                  "404": {
+                    "description": "No #{model} found",
+                  },
+                },
+              },
+              "delete": {
+                "summary": "Delete",
+                "description": "Deletes the #{model}",
+                "parameters": [
+                  {
+                    "name": "id",
+                    "in": "path",
+                    "required": true,
+                    "schema": {
+                      "type": "integer",
+                    },
+                  },
+                ],
+                "tags": [model.classify],
+                "security": [
+                  "bearerAuth": [],
+                ],
+                "responses": {
+                  "200": {
+                    "description": "#{model} Deleted",
+                  },
+                  "404": {
+                    "description": "No #{model} found",
+                  },
+                },
+              },
+              "get": {
+                "summary": "Show",
+                "description": "Shows the #{model}",
+                "parameters": [
+                  {
+                    "name": "id",
+                    "in": "path",
+                    "required": true,
+                    "schema": {
+                      "type": "integer",
+                    },
+                  },
+                ],
+                "tags": [model.classify],
+                "security": [
+                  "bearerAuth": [],
+                ],
+                "responses": {
+                  "200": {
+                    "description": "Show #{model}",
+                    "content": {
+                      "application/json": {
+                        "schema": {
+                          "type": "object",
+                          "properties": create_properties_from_model(d, (d.json_attrs rescue {})),
+                        },
+                      },
+                    },
+                  },
+                  "404": {
+                    "description": "No #{model} found",
+                  },
+                },
+              },
+            }
+            # d.columns_hash.each_pair do |key, val|
+            #   pivot[model][key] = val.type unless key.ends_with? "_id"
+            # end
+            # # Only application record descendants in order to have a clean schema
+            # pivot[model][:associations] ||= {
+            #   has_many: d.reflect_on_all_associations(:has_many).map { |a|
+            #     a.name if (((a.options[:class_name].presence || a.name).to_s.classify.constantize.new.is_a? ApplicationRecord) rescue false)
+            #   }.compact,
+            #   belongs_to: d.reflect_on_all_associations(:belongs_to).map { |a|
+            #     a.name if (((a.options[:class_name].presence || a.name).to_s.classify.constantize.new.is_a? ApplicationRecord) rescue false)
+            #   }.compact
+            # }
+            # pivot[model][:methods] ||= (d.instance_methods(false).include?(:json_attrs) && !d.json_attrs.blank?) ? d.json_attrs[:methods] : nil
+          end
+        end
+        pivot
+      end
+
+      def description
+        info_description
+      end
+
+      private
+
+      def info_description
+        info = <<-MARKDOWN
+
+## About this API Documentation
+
+Model Driven Backend [API](https://github.com/gabrieletassoni/thecore/blob/master/docs/04_REST_API.md) created to reflect the actual Active Record Models present in the project in a dynamic way.
+
+This swagger describes all the CRUD endpoints provided by the application, as well as all the custom endpoints and gives a deep dive into the parameters accepted in GET (Index) requests and POST (Search) requests. Since the controller unifies params (via request.parameters), the filtering logic is identical whether parameters are passed in the Query String (GET) or the JSON Body (POST).
+
+The documentation starts from the authentication mechanism, integrated with the details from the provided code.
+Here is the updated and integrated documentation for the Authentication mechanism. It now covers the full lifecycle: obtaining the initial token via the login endpoint and maintaining the session via the sliding expiration mechanism found in the controller.
+
+---
+
+## Authentication & Token Management
+
+The API implements a **stateless JWT (JSON Web Token)** authentication mechanism. It consists of two distinct phases:
+
+1. **Initial Authentication:** Exchanging credentials for the first Token.
+2. **Session Maintenance:** Using a **Sliding Expiration** strategy where every subsequent successful request issues a fresh token.
+
+### 1. Initial Authentication (Login)
+
+To begin a session, the client must POST user credentials to the authentication endpoint. This is the only request that does not require an `Authorization` header.
+
+#### Request
+
+**Endpoint:** `POST /api/v2/authenticate`
+
+**Body:**
+
+```json
+{
+    "auth": {
+        "email": "admin@example.com",
+        "password": "Change#1"
+    }
+}
+
+```
+
+#### Response
+
+Upon successful authentication, the server returns two critical pieces of data:
+
+1. **Response Body:** Contains the User object details.
+2. **Response Headers:** Contains the initial JWT in the `token` header.
+
+**Example Body:**
+
+```json
+{
+    "id": 219,
+    "email": "admin@example.com",
+    "created_at": "2025-12-10T07:57:54.336Z",
+    "admin": true,
+    "locked": false,
+    "locale": "en",
+    // ... other user attributes
+    "roles": []
+}
+
+```
+
+**Example Headers:**
+Note the presence of the `token` header.
+
+```http
+HTTP/1.1 200 OK
+content-type: application/json; charset=utf-8
+token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyMTksImV4cCI6MTc2NjQ3ODMwN30.I0qJzOwA0Jxx0frL5-9jVH2PsakdZjSEY8Kqb9S3GKo
+x-request-id: 113cad63-11f8-4daf-b684-19322a053bcc
+...
+
+```
+
+---
+
+### 2. Sliding Expiration (Token Renewal)
+
+Once the client has the initial token, the `Api::V2::ApplicationController` handles the lifecycle. Instead of a fixed expiration time that forces a re-login, the API issues a **brand new token** with every successfully authenticated request.
+
+#### The Renewal Mechanism
+
+1. **Client Request:** The client sends the *current* token in the `Authorization` header.
+```http
+Authorization: Bearer <Current_Token>
+
+```
+
+
+2. **Verification:** The `authenticate_request` method verifies the token. If valid, it sets `@current_user`.
+3. **Renewal:** Before sending the response, the controller generates a new JWT encoded with the current user's ID and sets it in the response header.
+```ruby
+response.set_header("Token", JsonWebToken.encode(user_id: current_user.id))
+
+```
+
+#### Client-Side Implementation Guide
+
+To maintain a valid session, the client must implement an interceptor to handle token rotation:
+
+1. **Login:** Call `/api/v2/authenticate` and store the `token` from the response header.
+2. **Subsequent Requests:** Attach the stored token to the `Authorization: Bearer ...` header.
+3. **Update Storage:**
+* Check every response for a `Token` header.
+* **If present:** Immediately replace the stored token with this new value.
+* **If missing:** Continue using the existing token (unless the response was a 401/403 error).
+
+#### Failure Scenarios
+
+If the `authenticate_request` fails (e.g., token expired, invalid signature):
+
+* The controller returns an unauthenticated error (`unauthenticated!`).
+* The execution halts, and the line generating the new header is never reached.
+* **Result:** The client receives a 401 error and **no new token**, signaling that the user must perform the **Initial Authentication** (login) again.
+
+---
+
+## API Documentation: Search, Filtering, and Pagination Parameters
+
+### 1. Pagination and Counting
+
+These parameters control the amount of data returned and navigation through result pages.
+
+* **`page`** (Integer): Indicates the page number to retrieve. If omitted, pagination is not applied (or defaults to the model's Kaminari configuration).
+* **`per`** (Integer): Indicates the number of records per page. Works in conjunction with `page`.
+* **`count`** (Boolean/Any value): If present and not empty, the API **does not** return the list of records but a JSON object containing only the total count of records matching the search criteria (e.g., `{ "count": 42 }`). Useful for displaying total results before loading them.
+
+### 2. Field Selection
+
+It is possible to limit the fields returned in the JSON response or include associations. The controller looks for these parameters in `a` or `json_attrs`.
+
+* **`a`** (or `json_attrs`): An object or hash defining the output JSON structure.
+* **`only`**: Array of strings. Returns only the specified attributes of the main model.
+* **`methods`**: Array of strings. Includes model methods that are not database columns.
+* **`include`**: Object for including relationships (associations). Associations can also have their own `only` or `methods`.
+
+### 3. Custom Actions
+
+* **`do`**: Specifies a custom action (`custom_action`) to execute on the model instead of the standard `index`.
+* Format: `?do=action_name` or `?do=action_name-token`.
+* The controller will look for a class method `custom_action_action_name` or a module `Endpoints::Model`.
+
+### 4. Filters and Sorting (Ransack)
+
+The core of the search functionality lies in the **`q`** parameter. The controller implements the **Ransack** gem, allowing for complex queries, filtering on associations, and dynamic sorting.
+
+Basic structure: `q[field_name_predicate]=value`
+
+#### Common Predicates (Suffixes)
+
+* `_eq`: Equal to (e.g., `status_eq`).
+* `_cont`: Contains (LIKE %value%, case insensitive).
+* `_start`: Starts with.
+* `_end`: Ends with.
+* `_gt` / `_lt`: Greater than / Less than (for numbers or dates).
+* `_gteq` / `_lteq`: Greater than or equal to / Less than or equal to.
+* `_in`: Included in a list (accepts an array).
+* `_present`: If set to `1` or `true`, filters for non-null values. `_blank` for nulls.
+
+#### Sorting
+
+* `s`: Defines the sorting order. Format: `field_name asc` or `field_name desc`.
+
+---
+
+## Practical Examples
+
+Below are two usage scenarios to achieve the same result: a **GET** request (URL parameters) and a **POST** request (JSON Body parameters).
+
+#### Scenario A: Simple Search and Pagination
+
+**Goal:** Find users whose name contains "Mario", paginated (page 2, 10 per page).
+
+##### 1. Using GET (Query String)
+
+Parameters are "flattened" and encoded in the URL.
+
+```text
+GET /api/v2/users?q[name_cont]=Mario&page=2&per=10
+
+```
+
+##### 2. Using POST (JSON Body)
+
+Ideal for complex searches to avoid exceeding URL length limits.
+
+```json
+POST /api/v2/users/search
+Content-Type: application/json
+
+{
+  "q": {
+    "name_cont": "Mario"
+  },
+  "page": 2,
+  "per": 10
+}
+
+```
+
+---
+
+#### Scenario B: Advanced Search, Sorting, and Field Selection
+
+**Goal:**
+
+1. Search for orders (`orders`) where `total_price` is greater than 50.
+2. Belonging to a user (`user`) whose email ends with `@test.com`.
+3. Sort by creation date descending.
+4. Return only the `id` and `total_price` of the order, including the `email` of the associated user.
+
+##### 1. Using GET (Query String)
+
+Note the square bracket syntax for nested structures (`q`, `a`).
+
+```text
+GET /api/v2/orders?q[total_price_gt]=50&q[user_email_end]=@test.com&q[s]=created_at desc&a[only][]=id&a[only][]=total_price&a[include][user][only][]=email
+
+```
+
+##### 2. Using POST (JSON Body)
+
+Much more readable for nested structures like `a` (json_attrs).
+
+```json
+POST /api/v2/orders/search
+Content-Type: application/json
+
+{
+  "q": {
+    "total_price_gt": 50,
+    "user_email_end": "@test.com",
+    "s": "created_at desc"
+  },
+  "a": {
+    "only": ["id", "total_price"],
+    "include": {
+      "user": {
+        "only": ["email"]
+      }
+    }
+  }
+}
+
+```
+
+---
+
+#### Scenario C: Multiple Search (OR) and Arrays
+
+**Goal:** Find products where status is "new" **OR** "refurbished" (using `_in`).
+
+##### 1. Using GET (Query String)
+
+To pass an array in GET, repeat the empty square brackets `[]`.
+
+```text
+GET /api/v2/products?q[status_in][]=new&q[status_in][]=refurbished
+
+```
+
+##### 2. Using POST (JSON Body)
+
+```json
+POST /api/v2/products/search
+Content-Type: application/json
+
+{
+  "q": {
+    "status_in": ["new", "refurbished"]
+  }
+}
+
+```
+
+---
+
+#### Scenario D: Count Only
+
+**Goal:** Know how many users are active without downloading the data.
+
+##### 1. Using GET
+
+```text
+GET /api/v2/users?q[active_eq]=true&count=true
+
+```
+
+##### 2. Using POST
+
+```json
+POST /api/v2/users/search
+Content-Type: application/json
+
+{
+  "q": {
+    "active_eq": true
+  },
+  "count": true
+}
+
+```
+
+**Expected Response:**
+
+```json
+{
+  "count": 156
+}
+
+```
+
+## ActiveStorage Integration: React Frontend & Rails Backend
+
+### Overview
+
+This guide explains how to handle file uploads (via Camera or Gallery) and attachment deletions using a **React** frontend and a **Ruby on Rails** backend.
+
+The Rails model uses a virtual attribute strategy for deletion:
+
+* **Upload:** handled via `has_many_attached :assets`
+* **Deletion:** handled via `attr_accessor :remove_assets`
+
+---
+
+### 1. Handling File Objects (No "Paths" needed)
+
+In a web/mobile context (React Web or PWA), you do not need a file system path. When a user takes a photo or selects a file, the browser creates a native **`File`** object (a type of `Blob`).
+
+You must send this binary object to the backend using **`FormData`**.
+
+#### React Component Example
+
+This component handles:
+
+1. **File Input:** Supports both gallery selection and direct camera capture on mobile.
+2. **FormData:** Constructs the payload correctly for Rails.
+3. **API Call:** Sends the data via `fetch`.
+
+```jsx
+import React, { useState } from 'react';
+
+const ProductForm = () => {
+  const [title, setTitle] = useState('');
+  const [selectedFiles, setSelectedFiles] = useState([]);
+
+  // Handle file selection
+  const handleFileChange = (event) => {
+    // event.target.files is a FileList; convert to Array for convenience
+    const filesArray = Array.from(event.target.files);
+    setSelectedFiles(filesArray);
+  };
+
+  // Handle form submission
+  const handleSubmit = async (event) => {
+    event.preventDefault();
+
+    // 1. Create the FormData object
+    const formData = new FormData();
+
+    // 2. Append text fields
+    formData.append('product[title]', title);
+
+    // 3. Append FILES
+    // It is crucial to use 'product[assets][]' with brackets.
+    // This tells Rails to treat it as an array of attachments.
+    selectedFiles.forEach((file) => {
+      formData.append('product[assets][]', file);
+    });
+
+    try {
+      const response = await fetch('http://localhost:3000/api/products', {
+        method: 'POST',
+        // IMPORTANT NOTE:
+        // When using FormData, do NOT set 'Content-Type': 'application/json'
+        // and do NOT manually set 'multipart/form-data'.
+        // The browser will automatically set the header with the correct 'boundary'.
+        body: formData,
+      });
+
+      if (response.ok) {
+        console.log("Upload successful!");
+        // Reset form or redirect...
+      } else {
+        console.error("Upload error");
+      }
+    } catch (error) {
+      console.error("Network error:", error);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit} style={{ padding: '20px' }}>
+      <div>
+        <label>Product Title:</label>
+        <input
+          type="text"
+          value={title}
+          onChange={(e) => setTitle(e.target.value)}
+        />
+      </div>
+
+      <div style={{ marginTop: '20px' }}>
+        <label>Photos (Camera or Gallery):</label>
+        {/* accept="image/*": Accepts only images.
+           capture="environment": On mobile, opens the rear camera directly.
+           Remove 'capture' if you want the user to choose between Gallery and Camera.
+           multiple: Allows selecting multiple photos.
+        */}
+        <input
+          type="file"
+          accept="image/*"
+          multiple
+          onChange={handleFileChange}
+        />
+      </div>
+
+      <button type="submit" style={{ marginTop: '20px' }}>
+        Save Product
+      </button>
+    </form>
+  );
+};
+
+export default ProductForm;
+
+```
+
+---
+
+### 2. Key Implementation Details
+
+#### A. The `capture` Attribute
+
+* `<input type="file" capture="environment" />`: Opens the **rear camera** directly on iOS/Android.
+* `<input type="file" capture="user" />`: Opens the **front camera** (selfie mode).
+* **No `capture` attribute** (but with `accept="image/*"`): The device will prompt the user: *"Take Photo or Photo Library?"*. This is often the best UX.
+
+#### B. The `forEach` Loop
+
+You cannot pass an array directly into `FormData` (e.g., `formData.append('key', myArray)` will not work).
+Rails expects multiple values for the same key. You must append each file individually:
+
+```javascript
+// Correct
+files.forEach(file => formData.append('product[assets][]', file));
+
+```
+
+#### C. The Content-Type Header
+
+This is a common pitfall. When using `fetch` or `axios` with a `FormData` body, **do not set the Content-Type header manually**.
+The browser must generate it automatically to include the boundary:
+`Content-Type: multipart/form-data; boundary=----WebKitFormBoundary...`
+
+---
+
+## 3. Handling Deletion (PATCH Request)
+
+To remove specific attachments using the `remove_assets` virtual attribute defined in your Rails model, send the **Attachment IDs** (not the file objects).
+
+```javascript
+const handleUpdate = async () => {
+  const formData = new FormData();
+
+  // 1. Add new files (if any)
+  newFiles.forEach(file => formData.append('product[assets][]', file));
+
+  // 2. Add IDs to remove
+  // (e.g., idsToRemove is an array like [12, 45])
+  idsToRemove.forEach(id => formData.append('product[remove_assets][]', id));
+
+  await fetch(`http://localhost:3000/api/products/${productId}`, {
+    method: 'PATCH',
+    body: formData
+  });
+};
+
+```
+
+### 4. Bare Metal HTTP Requests
+
+If you were to inspect the network traffic or manually construct the request (e.g., using raw sockets or a tool like Postman/Insomnia), this is exactly what the payload looks like "over the wire."
+
+#### A. POST Request (Upload)
+
+Notice how `multipart/form-data` uses a **boundary** string (randomly generated by the client) to separate different fields.
+
+```http
+POST /api/products HTTP/1.1
+Host: localhost:3000
+Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
+
+------WebKitFormBoundary7MA4YWxkTrZu0gW
+Content-Disposition: form-data; name="product[title]"
+
+My New Product
+------WebKitFormBoundary7MA4YWxkTrZu0gW
+Content-Disposition: form-data; name="product[assets][]"; filename="camera_shot.jpg"
+Content-Type: image/jpeg
+
+(Binary image data goes here...)
+------WebKitFormBoundary7MA4YWxkTrZu0gW
+Content-Disposition: form-data; name="product[assets][]"; filename="gallery_photo.png"
+Content-Type: image/png
+
+(Binary image data goes here...)
+------WebKitFormBoundary7MA4YWxkTrZu0gW--
+
+```
+
+#### B. PATCH Request (Deletion via IDs)
+
+When sending the `remove_assets` array via `FormData`, the key is repeated for every ID. This is how HTTP handles arrays in form data.
+
+```http
+PATCH /api/products/100 HTTP/1.1
+Host: localhost:3000
+Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryXyZ123
+
+------WebKitFormBoundaryXyZ123
+Content-Disposition: form-data; name="product[remove_assets][]"
+
+12
+------WebKitFormBoundaryXyZ123
+Content-Disposition: form-data; name="product[remove_assets][]"
+
+45
+------WebKitFormBoundaryXyZ123--
+
+```
+        MARKDOWN
+        info
+      end
+    end
+  end
+end