brainstem 2.0.0 → 2.1.0

data/spec/brainstem/cli/generate_api_docs_command_spec.rb

@@ -119,6 +119,14 @@ module Brainstem
           end
         end
 
+        context "when --include-internal" do
+          let(:args) { %w(--include-internal) }
+
+          it "sets the internal option in the args for atlas" do
+            expect(subject.options[:builder][:args_for_atlas][:include_internal]).to eq true
+          end
+        end
+
         context "when --oas-filename-pattern" do
           let(:args) { %w(--oas-filename-pattern=blah/{{version}}.{{extension}}) }
 

data/spec/brainstem/concerns/controller_dsl_spec.rb

@@ -13,7 +13,15 @@ module Brainstem
       end
 
       describe ".nodoc!" do
-        it "sets the config nodoc to true" do
+        it "sets the config nodoc to passed in description" do
+          subject.brainstem_params do
+            nodoc! "Description for why these are nodoc"
+          end
+
+          expect(subject.configuration[:_default][:nodoc]).to eq "Description for why these are nodoc"
+        end
+
+        it "sets the config nodoc to default value (true)" do
           subject.brainstem_params do
             nodoc!
           end
@@ -22,6 +30,24 @@ module Brainstem
         end
       end
 
+      describe ".internal!" do
+        it "sets the config internal to passed in description" do
+          subject.brainstem_params do
+            internal! "Description for why these are internal docs"
+          end
+
+          expect(subject.configuration[:_default][:internal]).to eq "Description for why these are internal docs"
+        end
+
+        it "sets the config internal to default value (true)" do
+          subject.brainstem_params do
+            internal!
+          end
+
+          expect(subject.configuration[:_default][:internal]).to eq true
+        end
+      end
+
       describe ".brainstem_params" do
         it "evaluates the given block in the class context" do
           mock(subject).configuration
@@ -388,43 +414,6 @@ module Brainstem
               expect(template_key.call).to eq('template')
               expect(valid_params[template_key][:required]).to be_falsey
             end
-
-            context "when one of the nested fields is required" do
-              it "sets the required attribute for the parent configuration to true" do
-                subject.brainstem_params do
-                  valid :template, :hash do |param|
-                    param.valid :id, :integer, required: true
-                    param.valid :title, :string
-                  end
-
-                  model_params :sprocket do |param|
-                    param.valid :details, :hash do |nested_param|
-                      nested_param.valid :data, :hash do |double_nested_param|
-                        double_nested_param.valid :raw_text, :string, required: true
-                      end
-                    end
-                  end
-                end
-
-                valid_params = subject.configuration[:_default][:valid_params]
-
-                template_key = valid_params.keys[0]
-                expect(template_key.call).to eq('template')
-                expect(valid_params[template_key][:required]).to be_truthy
-
-                sprocket_details_key = valid_params.keys[3]
-                expect(sprocket_details_key.call).to eq('details')
-                expect(valid_params[sprocket_details_key][:required]).to be_truthy
-
-                sprocket_details_data_key = valid_params.keys[4]
-                expect(sprocket_details_data_key.call).to eq('data')
-                expect(valid_params[sprocket_details_data_key][:required]).to be_truthy
-
-                sprocket_details_data_raw_text_key = valid_params.keys[5]
-                expect(sprocket_details_data_raw_text_key.call).to eq('raw_text')
-                expect(valid_params[sprocket_details_data_raw_text_key][:required]).to be_truthy
-              end
-            end
           end
 
           context "when root is nodoc" do
@@ -524,6 +513,171 @@ module Brainstem
             end
           end
         end
+
+        context "when the param has a dynamic key" do
+          let(:dynamic_keyword) { described_class::DYNAMIC_KEY.to_s }
+
+          it "sets the dynamic key property" do
+            subject.brainstem_params do
+              valid :id, :integer
+              valid :_dynamic_key, :string, required: true
+              valid :user_id, :integer, dynamic_key: true
+            end
+
+            valid_params = subject.configuration[:_default][:valid_params]
+            expect(valid_params.keys.length).to eq(3)
+
+            id_config_key = valid_params.keys[0]
+            expect(id_config_key.call).to eq('id')
+            id_config = valid_params[id_config_key]
+            expect(id_config[:required]).to be_falsey
+            expect(id_config[:type]).to eq("integer")
+
+            dynamic_string_key = valid_params.keys[1]
+            expect(dynamic_string_key.call).to eq(dynamic_keyword)
+            dynamic_string_config = valid_params[dynamic_string_key]
+            expect(dynamic_string_config[:type]).to eq("string")
+            expect(dynamic_string_config[:required]).to be_truthy
+            expect(dynamic_string_config[:dynamic_key]).to be_truthy
+
+            dynamic_user_id_key = valid_params.keys[2]
+            expect(dynamic_user_id_key.call).to eq('user_id')
+            dynamic_user_id_config = valid_params[dynamic_user_id_key]
+            expect(dynamic_user_id_config[:type]).to eq("integer")
+            expect(dynamic_user_id_config[:dynamic_key]).to be_truthy
+          end
+        end
+      end
+
+      describe ".valid_dynamic_param" do
+        let(:dynamic_keyword) { described_class::DYNAMIC_KEY.to_s }
+        
+        it "sets the correct configuration" do
+          subject.brainstem_params do
+            valid_dynamic_param :integer,
+              info: "User ID is required",
+              required: true
+          end
+
+          valid_params = subject.configuration[:_default][:valid_params]
+          expect(valid_params.keys.length).to eq(1)
+          expect(valid_params.keys[0]).to be_a(Proc)
+          expect(valid_params.keys[0].call).to eq(dynamic_keyword)
+
+          sprocket_ids_config = valid_params[valid_params.keys[0]]
+          expect(sprocket_ids_config[:info]).to eq "User ID is required"
+          expect(sprocket_ids_config[:required]).to be_truthy
+          expect(sprocket_ids_config[:type]).to eq("integer")
+          expect(sprocket_ids_config[:dynamic_key]).to be_truthy
+        end
+
+        context "when type is hash" do
+          it "adds the nested fields to valid params" do
+            subject.brainstem_params do
+              valid :id, :integer
+
+              valid :info, :hash, required: true do |param|
+                param.valid_dynamic_param :string, required: true
+
+                param.valid :data, :hash do |double_nested_param|
+                  double_nested_param.valid_dynamic_param :string
+                end
+              end
+            end
+
+            valid_params = subject.configuration[:_default][:valid_params]
+            param_keys = valid_params.keys
+            expect(param_keys.length).to eq(5)
+
+            expect(param_keys[0].call).to eq('id')
+            id_config = valid_params[param_keys[0]]
+            expect(id_config[:root]).to be_nil
+            expect(id_config[:ancestors]).to be_nil
+
+            expect(param_keys[1].call).to eq('info')
+            info_key = param_keys[1]
+            info_config = valid_params[info_key]
+            expect(info_config[:root]).to be_nil
+            expect(info_config[:ancestors]).to be_nil
+
+            expect(param_keys[2].call).to eq(dynamic_keyword)
+            dynamic_info_nested_config = valid_params[param_keys[2]]
+            expect(dynamic_info_nested_config[:root]).to be_nil
+            expect(dynamic_info_nested_config[:ancestors]).to eq([info_key])
+            expect(dynamic_info_nested_config[:dynamic_key]).to be_truthy
+            expect(dynamic_info_nested_config[:required]).to be_truthy
+
+            expect(param_keys[3].call).to eq('data')
+            details_data_key = param_keys[3]
+            details_data_config = valid_params[details_data_key]
+            expect(details_data_config[:root]).to be_nil
+            expect(details_data_config[:ancestors]).to eq([info_key])
+
+            expect(param_keys[4].call).to eq(dynamic_keyword)
+            dynamic_data_nested_config = valid_params[param_keys[4]]
+            expect(dynamic_data_nested_config[:root]).to be_nil
+            expect(dynamic_data_nested_config[:ancestors]).to eq([info_key, details_data_key])
+          end
+        end
+
+        context "when type is array" do
+          it "sets the type and sub type appropriately" do
+            subject.brainstem_params do
+              valid :sprocket_ids, :array,
+                    required: true,
+                    item_type: :string
+            end
+
+            valid_params = subject.configuration[:_default][:valid_params]
+
+            sprocket_ids_key = valid_params.keys[0]
+            expect(sprocket_ids_key.call).to eq('sprocket_ids')
+
+            sprocket_ids_config = valid_params[sprocket_ids_key]
+            expect(sprocket_ids_config[:required]).to be_truthy
+            expect(sprocket_ids_config[:type]).to eq('array')
+            expect(sprocket_ids_config[:item_type]).to eq('string')
+          end
+
+          context "when a block is given" do
+            it "sets the type and sub type appropriately" do
+              subject.brainstem_params do
+                valid :sprocket_tasks, :array, required: true, item_type: 'hash' do |param|
+                  param.valid :task_id, :integer, required: true
+                  param.valid :task_title, :string
+                end
+              end
+
+              valid_params = subject.configuration[:_default][:valid_params]
+
+              sprocket_tasks_key = valid_params.keys[0]
+              expect(sprocket_tasks_key.call).to eq('sprocket_tasks')
+
+              sprocket_tasks_config = valid_params[sprocket_tasks_key]
+              expect(sprocket_tasks_config[:required]).to be_truthy
+              expect(sprocket_tasks_config[:type]).to eq('array')
+              expect(sprocket_tasks_config[:item_type]).to eq('hash')
+
+              task_id_key = valid_params.keys[1]
+              expect(task_id_key.call).to eq('task_id')
+
+              task_id_config = valid_params[task_id_key]
+              expect(task_id_config[:required]).to be_truthy
+              expect(task_id_config[:type]).to eq('integer')
+              expect(task_id_config[:root]).to be_nil
+              expect(task_id_config[:ancestors]).to eq([sprocket_tasks_key])
+
+              task_title_key = valid_params.keys[2]
+              expect(task_title_key.call).to eq('task_title')
+
+              task_title_config = valid_params[task_title_key]
+              expect(task_title_config[:required]).to be_falsey
+              expect(task_title_config[:type]).to eq('string')
+              expect(task_title_config[:root]).to be_nil
+              expect(task_title_config[:ancestors]).to eq([sprocket_tasks_key])
+            end
+          end
+        end
       end
 
       describe ".transform" do
@@ -721,6 +875,114 @@ module Brainstem
               required: false,
             }.with_indifferent_access)
           end
+
+          context "when key is dynamic" do
+            it "sets the custom_response configuration" do
+              subject.brainstem_params do
+                actions :show do
+                  response :hash do |response_param|
+                    response_param.fields :mk, :hash do |dk|
+                      dk.dynamic_key_field :string,
+                        info: "I am a dynamic key field I"
+                      dk.field :mk_blah, :string,
+                        required: true
+                    end
+
+                    response_param.fields :mk2, :hash do |dk|
+                      dk.field :_dynamic_key, :string,
+                        required: true,
+                        info: "dynamic key field II"
+                    end
+
+                    response_param.dynamic_key_fields :hash do |dk|
+                      dk.field :user_id, :string,
+                        dynamic_key: true,
+                        info: "dynamic key field with dynamic_key attribute"
+                    end
+                  end
+                end
+              end
+
+              configuration = subject.configuration[:show][:custom_response]
+              expect(configuration).to be_present
+              expect(configuration[:_config]).to eq({
+                type: 'hash',
+                nodoc: false,
+                required: false,
+              }.with_indifferent_access)
+
+              param_keys = configuration.keys
+              expect(param_keys.length).to eq(8)
+
+              mk_key = param_keys[1]
+              expect(mk_key.call).to eq('mk')
+              my_key_config = configuration.to_h[mk_key]
+              expect(my_key_config).to eq({
+                nodoc: false,
+                type: 'hash',
+                required: false,
+              }.with_indifferent_access)
+
+              mk_dynamic_key = param_keys[2]
+              mk_dynamic_config = configuration.to_h[mk_dynamic_key]
+              expect(mk_dynamic_config).to eq({
+                nodoc: false,
+                dynamic_key: true,
+                type: 'string',
+                ancestors: [mk_key],
+                required: false,
+                info: "I am a dynamic key field I"
+              }.with_indifferent_access)
+
+              mk_blah_key = param_keys[3]
+              mk_blah_config = configuration.to_h[mk_blah_key]
+              expect(mk_blah_config).to eq({
+                nodoc: false,
+                type: 'string',
+                ancestors: [mk_key],
+                required: true,
+              }.with_indifferent_access)
+
+              mk2_key = param_keys[4]
+              mk2_config = configuration.to_h[mk2_key]
+              expect(mk2_config).to eq({
+                nodoc: false,
+                type: 'hash',
+                required: false,
+              }.with_indifferent_access)
+
+              mk2_dynamic_key = param_keys[5]
+              mk2_dynamic_config = configuration.to_h[mk2_dynamic_key]
+              expect(mk2_dynamic_config).to eq({
+                nodoc: false,
+                dynamic_key: true,
+                type: 'string',
+                ancestors: [mk2_key],
+                required: true,
+                info: "dynamic key field II",
+              }.with_indifferent_access)
+
+              dynamic_key = param_keys[6]
+              dynamic_config = configuration.to_h[dynamic_key]
+              expect(dynamic_config).to eq({
+                nodoc: false,
+                dynamic_key: true,
+                type: 'hash',
+                required: false,
+              }.with_indifferent_access)
+
+              dynamic_child_key = param_keys[7]
+              dynamic_child_config = configuration.to_h[dynamic_child_key]
+              expect(dynamic_child_config).to eq({
+                nodoc: false,
+                dynamic_key: true,
+                ancestors: [dynamic_key],
+                type: 'string',
+                required: false,
+                info: "dynamic key field with dynamic_key attribute",
+              }.with_indifferent_access)
+            end
+          end
         end
 
         context "when block not given" do
@@ -740,6 +1002,45 @@ module Brainstem
               required: false,
             }.with_indifferent_access)
           end
+
+          context "when response is a nested array of strings" do
+            it "sets the custom_response configuration" do
+              subject.brainstem_params do
+                actions :show do
+                  response :array, nested_levels: 2, item_type: :string
+                end
+              end
+
+              configuration = subject.configuration[:show][:custom_response]
+              expect(configuration).to be_present
+              expect(configuration[:_config]).to eq({
+                type: 'array',
+                item_type: 'string',
+                nested_levels: 2,
+                nodoc: false,
+                required: false,
+              }.with_indifferent_access)
+            end
+
+            context "when the nested level is less than 2" do
+              it "does not return a config with a `nested_levels` key" do
+                subject.brainstem_params do
+                  actions :show do
+                    response :array, nested_levels: 1, item_type: :string
+                  end
+                end
+
+                configuration = subject.configuration[:show][:custom_response]
+                expect(configuration).to be_present
+                expect(configuration[:_config]).to eq({
+                  type: 'array',
+                  item_type: 'string',
+                  nodoc: false,
+                  required: false,
+                }.with_indifferent_access)
+              end
+            end
+          end
         end
       end
 
@@ -796,8 +1097,13 @@ module Brainstem
               subject.brainstem_params do
                 actions :show do
                   response :hash do
-                    fields :contacts, :array do
-                      field :full_name, :string
+                    fields :contacts, :array do |contact|
+                      contact.field :full_name, :string
+                      contact.field :friends, :array, nested_levels: 3, item_type: :string
+                      contact.field :enemies, :array, nested_levels: 1, item_type: :string
+                      contact.fields :frenemies, :array, nested_levels: 2 do |frenemy|
+                        frenemy.field :jim, :string
+                      end
                     end
                   end
                 end
@@ -806,20 +1112,63 @@ module Brainstem
               configuration = subject.configuration[:show][:custom_response]
               param_keys = configuration.keys
 
-              expect(param_keys[1].call).to eq('contacts')
-              expect(configuration[param_keys[1]]).to eq({
+              contacts_proc = param_keys[1]
+              expect(contacts_proc.call).to eq('contacts')
+              expect(configuration[contacts_proc]).to eq({
                 type: 'array',
                 item_type: 'hash',
                 nodoc: false,
                 required: false,
               }.with_indifferent_access)
 
-              expect(param_keys[2].call).to eq('full_name')
-              expect(configuration[param_keys[2]]).to eq({
+              full_name_proc = param_keys[2]
+              expect(full_name_proc.call).to eq('full_name')
+              expect(configuration[full_name_proc]).to eq({
                 type: 'string',
                 nodoc: false,
                 required: false,
-                ancestors: [param_keys[1]]
+                ancestors: [contacts_proc]
+              }.with_indifferent_access)
+
+              friends_proc = param_keys[3]
+              expect(friends_proc.call).to eq('friends')
+              expect(configuration[friends_proc]).to eq({
+                type: 'array',
+                item_type: 'string',
+                nested_levels: 3,
+                nodoc: false,
+                required: false,
+                ancestors: [contacts_proc]
+              }.with_indifferent_access)
+
+              enemies_proc = param_keys[4]
+              expect(enemies_proc.call).to eq('enemies')
+              expect(configuration[enemies_proc]).to eq({
+                type: 'array',
+                item_type: 'string',
+                nodoc: false,
+                required: false,
+                ancestors: [contacts_proc]
+              }.with_indifferent_access)
+
+              frenemies_proc = param_keys[5]
+              expect(frenemies_proc.call).to eq('frenemies')
+              expect(configuration[frenemies_proc]).to eq({
+                type: 'array',
+                nested_levels: 2,
+                item_type: 'hash',
+                nodoc: false,
+                required: false,
+                ancestors: [contacts_proc]
+              }.with_indifferent_access)
+
+              jim_proc = param_keys[6]
+              expect(jim_proc.call).to eq('jim')
+              expect(configuration[jim_proc]).to eq({
+                type: 'string',
+                nodoc: false,
+                required: false,
+                ancestors: [contacts_proc, frenemies_proc]
               }.with_indifferent_access)
             end
           end
@@ -868,6 +1217,119 @@ module Brainstem
         end
       end
 
+      describe ".dynamic_key_fields" do
+        context "when used outside of the response block" do
+          it "raises an error" do
+            expect {
+              subject.brainstem_params do
+                actions :show do
+                  dynamic_key_fields :array do
+                    field :full_name, :string
+                  end
+                end
+              end
+            }.to raise_error(StandardError)
+          end
+        end
+
+        context "when used within the response block" do
+          let(:dynamic_keyword) { described_class::DYNAMIC_KEY.to_s }
+          
+          context "when type is hash" do
+            it "adds the field block to custom_response configuration" do
+              subject.brainstem_params do
+                actions :show do
+                  response :hash do
+                    dynamic_key_fields :hash do
+                      field :full_name, :string
+                    end
+                  end
+                end
+              end
+
+              configuration = subject.configuration[:show][:custom_response]
+              param_keys = configuration.keys
+
+              expect(param_keys[1].call).to eq(dynamic_keyword)
+              expect(configuration[param_keys[1]]).to eq({
+                type: 'hash',
+                nodoc: false,
+                required: false,
+                dynamic_key: true,
+              }.with_indifferent_access)
+
+              expect(param_keys[2].call).to eq('full_name')
+              expect(configuration[param_keys[2]]).to eq({
+                type: 'string',
+                nodoc: false,
+                ancestors: [param_keys[1]],
+                required: false,
+              }.with_indifferent_access)
+            end
+          end
+
+          context "when type is array" do
+            it "adds the field block to custom_response configuration" do
+              subject.brainstem_params do
+                actions :show do
+                  response :hash do
+                    dynamic_key_fields :array do |contact|
+                      contact.field :full_name, :string
+                      contact.dynamic_key_fields :array, nested_levels: 2 do |frenemy|
+                        frenemy.field :jim, :string
+                      end
+                    end
+                  end
+                end
+              end
+
+              configuration = subject.configuration[:show][:custom_response]
+              param_keys = configuration.keys
+
+              dynamic_parent_proc = param_keys[1]
+              expect(dynamic_parent_proc.call).to eq(dynamic_keyword)
+              expect(configuration[dynamic_parent_proc]).to eq({
+                type: 'array',
+                item_type: 'hash',
+                nodoc: false,
+                required: false,
+                dynamic_key: true,
+              }.with_indifferent_access)
+
+              full_name_proc = param_keys[2]
+              expect(full_name_proc.call).to eq('full_name')
+              expect(configuration[full_name_proc]).to eq({
+                type: 'string',
+                nodoc: false,
+                required: false,
+                ancestors: [dynamic_parent_proc]
+              }.with_indifferent_access)
+
+              dynamic_nested_proc = param_keys[3]
+              expect(dynamic_nested_proc.call).to eq(dynamic_keyword)
+              expect(configuration[dynamic_nested_proc]).to eq({
+                type: 'array',
+                nested_levels: 2,
+                item_type: 'hash',
+                nodoc: false,
+                required: false,
+                ancestors: [dynamic_parent_proc],
+                dynamic_key: true,
+              }.with_indifferent_access)
+
+              jim_proc = param_keys[4]
+              expect(jim_proc.call).to eq('jim')
+              expect(configuration[jim_proc]).to eq({
+                type: 'string',
+                nodoc: false,
+                required: false,
+                ancestors: [dynamic_parent_proc, dynamic_nested_proc]
+              }.with_indifferent_access)
+            end
+          end
+        end
+      end
+
       describe ".field" do
         context "when used outside of the response block" do
           it "raises an error" do
@@ -961,6 +1423,105 @@ module Brainstem
         end
       end
 
+      describe ".dynamic_key_field" do
+        let(:dynamic_keyword) { described_class::DYNAMIC_KEY.to_s }
+
+        context "when used outside of the response block" do
+          it "raises an error" do
+            expect {
+              subject.brainstem_params do
+                actions :show do
+                  dynamic_key_field :string
+                end
+              end
+            }.to raise_error(StandardError)
+          end
+        end
+
+        context "when used within the response block" do
+          context "when type is array" do
+            it "adds the field block to custom_response configuration" do
+              subject.brainstem_params do
+                actions :show do
+                  response :hash do
+                    dynamic_key_field :array
+                  end
+                end
+              end
+
+              configuration = subject.configuration[:show][:custom_response]
+              param_keys = configuration.keys
+
+              expect(param_keys[1].call).to eq(dynamic_keyword)
+              expect(configuration[param_keys[1]]).to eq({
+                type: 'array',
+                item_type: 'string',
+                nodoc: false,
+                required: false,
+                dynamic_key: true
+              }.with_indifferent_access)
+            end
+          end
+
+          context "when type is not array" do
+            it "adds the field block to custom_response configuration" do
+              subject.brainstem_params do
+                actions :show do
+                  response :hash do
+                    dynamic_key_field :string
+                  end
+                end
+              end
+
+              configuration = subject.configuration[:show][:custom_response]
+              param_keys = configuration.keys
+
+              expect(param_keys[1].call).to eq(dynamic_keyword)
+              expect(configuration[param_keys[1]]).to eq({
+                type: 'string',
+                nodoc: false,
+                required: false,
+                dynamic_key: true,
+              }.with_indifferent_access)
+            end
+          end
+
+          context "when nested under parent field" do
+            it "inherits the nodoc attribute" do
+              subject.brainstem_params do
+                actions :show do
+                  response :hash do
+                    dynamic_key_fields :hash, nodoc: true do
+                      dynamic_key_field :string
+                    end
+                  end
+                end
+              end
+
+              configuration = subject.configuration[:show][:custom_response]
+              param_keys = configuration.keys
+
+              expect(param_keys[1].call).to eq(dynamic_keyword)
+              expect(configuration[param_keys[1]]).to eq({
+                type: 'hash',
+                nodoc: true,
+                required: false,
+                dynamic_key: true,
+              }.with_indifferent_access)
+
+              expect(param_keys[2].call).to eq(dynamic_keyword)
+              expect(configuration[param_keys[2]]).to eq({
+                type: 'string',
+                nodoc: true,
+                required: false,
+                dynamic_key: true,
+                ancestors: [param_keys[1]]
+              }.with_indifferent_access)
+            end
+          end
+        end
+      end
+
       describe ".operation_id" do
         it "sets the operation_id for the context" do
           subject.brainstem_params do