bullet_train-api 1.7.10 → 1.7.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 832c27ca7af794811031cece070f5c19c3a711507a6acc02dee6b50a1ac2a7ca
-  data.tar.gz: 0a436d84fa41177ab407541f24e8af26afb5d96ae1e9417463a051a012079dc7
+  metadata.gz: aef8c20ab58036263c4aedee16b5957f9794f6db67388b88f308ad2de6eddcd2
+  data.tar.gz: c97837332c5bf099547093477248223dd5efecc9dfe6327b10e27173bff8b981
 SHA512:
-  metadata.gz: f5dd7ddc3e438803826251511d350708a7c9cc909c5633bd0e0da8352dc8c3571f5a4bfe2f2408906d2a01afb210bc5dfc0d14c49c25a641b4c286e3eda71051
-  data.tar.gz: a4d3b63282da9b6081c546754d6f9bb6fc2f6d490e5b1b5bfd087f1806774d2720c69c8c1d1dfb6ac49d1c293e10225b1b398b00f6ca9fbf31656ae49ae940f1
+  metadata.gz: f7b9c1c254e7425b2a5a48b1badf2a6b22667b4724e761291ee4a577bd048b3bfe3663864eb0a34bf653d54a4c741f044f1d6ac7a44e8b8d581e6303f082f6dc
+  data.tar.gz: 81ff21bf84669a24a2972fcc6b6441661c18e3074b31f1c94945572b4e34dfe4923ef21985b3adaa5e1c5bdc70353d82567853e1da03f49da8c22a2053eeda55

data/README.md

@@ -20,6 +20,7 @@ Then, run `bundle` or install it manually using `gem install bullet_train-api`.
 - [Documentation](#documentation)
   - [Index file](#index-file)
   - [Automatic Components](#automatic-components)
+  - [Manually Extending Component Schemas](#manually-extending-component-schemas)
   - [Automatic Paths](#automatic-paths)
   - [External Markdown files](#external-markdown-files)
   - [Examples](#examples)
@@ -144,6 +145,59 @@ As you can see, it automatically sets required fields based on presence validato
 field types based on the value found in Jbuilder file, descriptions and examples.
 More on how it works and how you can customize the output in [`jbuilder-schema`](https://github.com/bullet-train-co/jbuilder-schema) documentation.
 
+#### Manually Extending Component Schemas
+
+While `automatic_components_for` automatically adds parameters and attributes from your application, sometimes it is
+necessary to manually specify parameters and attributes in addition to the automatic ones, due to custom code in
+your app.
+
+`automatic_components_for` allows to you add or remove parameters and attributes. You can also specify that
+parameters that are only available for create or update methods.
+
+##### Adding or Removing Specific Attributes for a Component
+
+To add or remove specific attributes for a component:
+
+    automatic_components_for User,
+      parameters: {
+        add: {
+          tag_ids: {
+            type: :array,
+            items: {type: :integer},
+            description: "Array of Tag IDs for the User."
+          }
+        }
+      },
+      attributes: {
+        remove: [:email, :time_zone],
+        add: {
+          url: {
+            type: :string,
+            description: "The URL of the User's image."
+          }
+        }
+      }
+
+##### Specifying Parameters for Create or Update Methods
+
+To specify parameters that only exist for the create or update methods, use the following format:
+
+    automatic_components_for Enrollment,
+      parameters: {
+        create: {
+          add: {
+            user_id: {
+              type: :integer,
+              description: "ID of the User who enrolled.",
+              example: 42
+            }
+          }
+        },
+        update: {
+          remove: [:time_zone]
+        }
+      }
+
 #### Automatic Paths
 
 Method `automatic_paths_for` generates basic REST paths. It accepts model as it's argument.
@@ -155,7 +209,7 @@ a write action (i.e. create or update), then doc generation uses the `strong_par
 defined in the corresponding controller to generate the Parameters section in the schema.
 
 Automatic paths are generated for basic REST actions. You can customize those paths or add your own by creating a
-file at `app/views/api/<version>/open_api/<Model.underscore.plural>/_paths.yaml.erb`. For REST paths there's no need to 
+file at `app/views/api/<version>/open_api/<Model.underscore.plural>/_paths.yaml.erb`. For REST paths there's no need to
 duplicate all the schema, you can specify only what differs from auto-generated code.
 
 #### External Markdown files

data/app/helpers/api/open_api_helper.rb

@@ -100,24 +100,24 @@ module Api
       end
 
       if has_strong_parameters?("Api::#{@version.upcase}::#{model.name.pluralize}Controller".constantize)
-        strong_params_module = "Api::#{@version.upcase}::#{model.name.pluralize}Controller::StrongParameters".constantize
-        strong_parameter_keys = BulletTrain::Api::StrongParametersReporter.new(model, strong_params_module).report
-        if strong_parameter_keys.last.is_a?(Hash)
-          strong_parameter_keys += strong_parameter_keys.pop.keys
+        strong_parameter_keys = strong_parameter_keys_for(model.name, @version)
+
+        # Create separate parameter schema for create and update methods
+        create_parameters_output = process_strong_parameters(model, strong_parameter_keys, schema_json, "create", **options)
+        update_parameters_output = process_strong_parameters(model, strong_parameter_keys, schema_json, "update", **options)
+
+        # We need to skip TeamParameters, UserParameters & InvitationParametersUpdate as they are not present in
+        # the bullet train api schema
+        if model.name == "Team" || model.name == "User"
+          create_parameters_output = nil
+        elsif model.name == "Invitation"
+          update_parameters_output = nil
         end
 
-        parameters_output = JSON.parse(schema_json)
-        parameters_output["required"].select! { |key| strong_parameter_keys.include?(key.to_sym) }
-        parameters_output["properties"].select! { |key| strong_parameter_keys.include?(key.to_sym) }
-        parameters_output["example"]&.select! { |key, value| strong_parameter_keys.include?(key.to_sym) && value.present? }
-
-        # Allow customization of Parameters
-        customize_component!(parameters_output, options[:parameters]) if options[:parameters]
-
-        (
-          indent(attributes_output.to_yaml.gsub("---", "#{model.name.gsub("::", "")}Attributes:"), 3) +
-            indent("    " + parameters_output.to_yaml.gsub("---", "#{model.name.gsub("::", "")}Parameters:"), 3)
-        ).html_safe
+        output = indent(attributes_output.to_yaml.gsub("---", "#{model.name.gsub("::", "")}Attributes:"), 3)
+        output += indent("    " + create_parameters_output.to_yaml.gsub("---", "#{model.name.gsub("::", "")}Parameters:"), 3) if create_parameters_output
+        output += indent("    " + update_parameters_output.to_yaml.gsub("---", "#{model.name.gsub("::", "")}ParametersUpdate:"), 3) if update_parameters_output
+        output.html_safe
       else
 
         indent(attributes_output.to_yaml.gsub("---", "#{model.name.gsub("::", "")}Attributes:"), 3)
@@ -125,6 +125,37 @@ module Api
       end
     end
 
+    def process_strong_parameters(model, strong_parameter_keys, schema_json, method_type, **options)
+      parameters_output = JSON.parse(schema_json)
+      parameters_output["required"].select! { |key| strong_parameter_keys.include?(key.to_sym) }
+      parameters_output["properties"].select! { |key| strong_parameter_keys.include?(key.to_sym) }
+      parameters_output["example"]&.select! { |key, value| strong_parameter_keys.include?(key.to_sym) }
+
+      # Allow customization of Parameters
+      parameters_custom = options[:parameters][method_type] if options[:parameters].is_a?(Hash) && options[:parameters].key?(method_type)
+      parameters_custom ||= options[:parameters]
+      customize_component!(parameters_output, parameters_custom, method_type) if parameters_custom
+
+      # We need to wrap the example parameters with the model name as expected by the API controllers
+      if parameters_output["example"]
+        parameters_output["example"] = {model.model_name.param_key => parameters_output["example"]}
+      end
+
+      parameters_output
+    end
+
+    def strong_parameter_keys_for(model_name, version)
+      strong_params_module = "::Api::#{version.upcase}::#{model_name.pluralize}Controller::StrongParameters".constantize
+      strong_params_reporter = BulletTrain::Api::StrongParametersReporter.new(model_name.constantize, strong_params_module)
+      strong_parameter_keys = strong_params_reporter.report
+
+      if strong_parameter_keys.last.is_a?(Hash)
+        strong_parameter_keys += strong_parameter_keys.pop.keys
+      end
+
+      strong_parameter_keys
+    end
+
     def paths_for(model)
       for_model model do
         indent(render("api/#{@version}/open_api/#{model.name.underscore.pluralize}/paths"), 1)
@@ -154,9 +185,9 @@ module Api
       methods.include?("create") || methods.include?("update")
     end
 
-    def update_ref_values!(hash)
+    def update_ref_values!(hash, method_type = nil)
       hash.each do |key, value|
-        if key == "$ref" && value.is_a?(String) && !value.include?("Attributes")
+        if key == "$ref" && value.is_a?(String) && !value.include?("Attributes#{method_type.to_s.camelize}")
           # Extract the part after "#/components/schemas/"
           schema_part = value.split("#/components/schemas/").last
 
@@ -164,14 +195,14 @@ module Api
           camelized_schema = schema_part.split("/").map(&:camelize).join
 
           # Update the value
-          hash[key] = "#/components/schemas/#{camelized_schema}Attributes"
+          hash[key] = "#/components/schemas/#{camelized_schema}Attributes#{method_type.to_s.camelize}"
         elsif value.is_a?(Hash)
           # Recursively call the method for nested hashes
-          update_ref_values!(value)
+          update_ref_values!(value, method_type)
         elsif value.is_a?(Array)
           # Recursively call the method for each hash in the array
           value.each do |item|
-            update_ref_values!(item) if item.is_a?(Hash)
+            update_ref_values!(item, method_type) if item.is_a?(Hash)
           end
         end
       end
@@ -189,9 +220,25 @@ module Api
       end
     end
 
-    def customize_component!(original, custom)
+    # This allows for customization of the attribute and parameter components.
+    #
+    # General customizations for all methods:
+    #   automatic_components_for User,
+    #     attributes: {remove: [:email, :time_zone]}, parameters: {add: {email: {type: :string, required: true, example: "fred@example.com"}}
+    #   automatic_components_for User,
+    #     attributes: {remove: [:email, :time_zone]}, parameters: {remove: [:email, :time_zone, :locale]}
+    # Or specific customizations to parameters for create and update methods:
+    #   automatic_components_for User,
+    #     parameters: {update: {remove: [:email]}, create: {remove: [:time_zone]}},
+    #     attributes: {remove: [:email, :time_zone]}
+    def customize_component!(original, custom, method_type = nil)
       custom = custom.deep_stringify_keys.deep_transform_values { |v| v.is_a?(Symbol) ? v.to_s : v }
 
+      # Check if customizations are provided for specific HTTP methods
+      if custom.key?(method_type.to_s)
+        custom = custom[method_type.to_s]
+      end
+
       if custom.key?("add")
         custom["add"].each do |property, details|
           if details["required"]

data/app/views/api/v1/open_api/shared/_paths.yaml.erb

@@ -59,7 +59,7 @@
                 type: object
                 $ref: "#/components/schemas/ScaffoldingCompletelyConcreteTangibleThingParameters"
           example:
-            🚅 post_parameters
+            $ref: "#/components/schemas/ScaffoldingCompletelyConcreteTangibleThingParameters/example"
     responses:
       "404":
         description: "Not Found"
@@ -115,9 +115,9 @@
             properties:
               scaffolding_completely_concrete_tangible_thing:
                 type: object
-                $ref: "#/components/schemas/ScaffoldingCompletelyConcreteTangibleThingParameters"
+                $ref: "#/components/schemas/ScaffoldingCompletelyConcreteTangibleThingParametersUpdate"
           example:
-            🚅 put_parameters
+            $ref: "#/components/schemas/ScaffoldingCompletelyConcreteTangibleThingParametersUpdate/example"
     responses:
       "404":
         description: "Not Found"

data/app/views/api/v1/open_api/teams/_paths.yaml.erb

@@ -64,7 +64,7 @@
             properties:
               team:
                 type: object
-                $ref: "#/components/schemas/TeamParameters"
+                $ref: "#/components/schemas/TeamParametersUpdate"
           example:
             <%= FactoryBot.put_parameters(:team, version: @version) %>
     responses:

data/app/views/api/v1/open_api/users/_paths.yaml.erb

@@ -63,7 +63,7 @@
             properties:
               user:
                 type: object
-                $ref: "#/components/schemas/UserParameters"
+                $ref: "#/components/schemas/UserParametersUpdate"
           example:
             <%= FactoryBot.put_parameters(:user, version: @version) %>
     responses:

data/lib/bullet_train/api/example_bot.rb

@@ -43,11 +43,7 @@ module FactoryBot
 
         if method.end_with?("parameters")
           if has_strong_parameters?("::Api::#{version.upcase}::#{class_name.pluralize}Controller".constantize)
-            strong_params_module = "::Api::#{version.upcase}::#{class_name.pluralize}Controller::StrongParameters".constantize
-            strong_parameter_keys = BulletTrain::Api::StrongParametersReporter.new(class_name.constantize, strong_params_module).report
-            if strong_parameter_keys.last.is_a?(Hash)
-              strong_parameter_keys += strong_parameter_keys.pop.keys
-            end
+            strong_parameter_keys = strong_parameter_keys_for(class_name, version)
 
             output = _json_output(template, version, class_name, var_name, values)
 

data/lib/bullet_train/api/strong_parameters_reporter.rb

@@ -41,8 +41,16 @@ module BulletTrain
       #   end
       # end
 
-      def report
-        @filters = send(:"#{@model.name.split("::").last.underscore}_params")
+      def report(method_type = nil)
+        method_type = ["create", "update"].include?(method_type) ? method_type : nil
+        base_method_name = @model.name.split("::").last.underscore
+
+        # if available in the controller, it will use the 'update' strong params instead of the default strong params.
+        @filters = if method_type == "update" && respond_to?("#{base_method_name}_#{method_type}_params".to_sym, true)
+          send(:"#{base_method_name}_#{method_type}_params")
+        else
+          send(:"#{base_method_name}_params")
+        end
 
         # There's a reason I'm doing it this way.
         @filters

data/lib/bullet_train/api/version.rb

@@ -1,5 +1,5 @@
 module BulletTrain
   module Api
-    VERSION = "1.7.10"
+    VERSION = "1.7.11"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bullet_train-api
 version: !ruby/object:Gem::Version
-  version: 1.7.10
+  version: 1.7.11
 platform: ruby
 authors:
 - Andrew Culver
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-05-30 00:00:00.000000000 Z
+date: 2024-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: standard