brainstem 2.0.0 → 2.1.0

data/spec/brainstem/api_docs/formatters/open_api_specification/version_2/field_definitions/response_field_formatter_spec.rb

@@ -0,0 +1,413 @@
+require 'spec_helper'
+require 'brainstem/api_docs/formatters/open_api_specification/version_2/field_definitions/response_field_formatter'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module OpenApiSpecification
+        module Version2
+          module FieldDefinitions
+            describe ResponseFieldFormatter do
+              describe '#format' do
+                let(:endpoint) { OpenStruct.new(controller_name: 'Test', action: 'create') }
+                let(:field_name) { 'sprocket' }
+                let(:configuration_tree) { field_configuration_tree.with_indifferent_access }
+
+                subject { described_class.new(endpoint, field_name, configuration_tree).format }
+
+                context 'when formatting non-nested field' do
+                  let(:field_configuration_tree) do
+                    {
+                      _config: {
+                        type: 'string',
+                        info: 'The name of the sprocket'
+                      }
+                    }
+                  end
+
+                  it 'returns the formatted field schema' do
+                    expect(subject).to eq(
+                      'type' => 'string',
+                      'description' => 'The name of the sprocket.',
+                    )
+                  end
+                end
+
+                context 'when formatting nested field' do
+                  context 'when formatting an array field' do
+                    let(:field_configuration_tree) do
+                      {
+                        _config: {
+                          type: 'array',
+                          item_type: 'long',
+                        },
+                      }
+                    end
+
+                    it 'returns the formatted field schema' do
+                      expect(subject).to eq(
+                        'type' => 'array',
+                        'items' => {
+                          'type' => 'integer', 'format' => 'int64'
+                        }
+                      )
+                    end
+                  end
+
+                  context 'when formatting a nested array field with non nested data type' do
+                    let(:field_configuration_tree) do
+                      {
+                        _config: {
+                          type: 'array',
+                          nested_levels: 3,
+                          item_type: 'decimal',
+                        },
+                      }
+                    end
+
+                    it 'returns the formatted field schema' do
+                      expect(subject).to eq(
+                        'type' => 'array',
+                        'items' => {
+                          'type' => 'array',
+                          'items' => {
+                            'type' => 'array',
+                            'items' => {
+                              'type' => 'number',
+                              'format' => 'float'
+                            }
+                          }
+                        }
+                      )
+                    end
+                  end
+
+                  context 'when formatting a nested array field with objects' do
+                    let(:field_configuration_tree) do
+                      {
+                        _config: {
+                          type: 'array',
+                          nested_levels: 2,
+                          item_type: 'hash',
+                        },
+                        widget_name: {
+                          _config: {
+                            required: true,
+                            type: 'string',
+                            info: 'the name of the widget',
+                            nodoc: false
+                          },
+                        },
+                        widget_permissions: {
+                          _config: {
+                            type: 'array',
+                            item_type: 'hash',
+                            info: 'the permissions of the widget',
+                            nodoc: false
+                          },
+                          can_edit: {
+                            _config: {
+                              type: 'array',
+                              nested_levels: 3,
+                              item_type: 'boolean',
+                              nodoc: false
+                            },
+                          }
+                        },
+                      }
+                    end
+
+                    it 'formats a complicated tree with arrays and hashes as children' do
+                      expect(subject).to eq(
+                        'type' => 'array',
+                        'items' => {
+                          'type' => 'array',
+                          'items' => {
+                            'type' => 'object',
+                            'properties' => {
+                              'widget_name' => {
+                                'type' => 'string',
+                                'description' => 'The name of the widget.',
+                              },
+                              'widget_permissions' => {
+                                'type' => 'array',
+                                'description' => 'The permissions of the widget.',
+                                'items' => {
+                                  'type' => 'object',
+                                  'properties' => {
+                                    'can_edit' => {
+                                      'type' => 'array',
+                                      'items' => {
+                                        'type' => 'array',
+                                        'items' => {
+                                          'type' => 'array',
+                                          'items' => {
+                                            'type' => 'boolean'
+                                          }
+                                        }
+                                      }
+                                    }
+                                  }
+                                }
+                              }
+                            }
+                          }
+                        }
+                      )
+                    end
+                  end
+
+                  context 'when formatting a hash field' do
+                    let(:field_configuration_tree) do
+                      {
+                        _config: {
+                          type: 'hash',
+                          info: 'Details about the widget',
+                        },
+                        widget_name: {
+                          _config: {
+                            required: true,
+                            type: 'string',
+                            info: 'the name of the widget',
+                            nodoc: false
+                          },
+                        },
+                        widget_permissions: {
+                          _config: {
+                            type: 'array',
+                            item_type: 'string',
+                            info: 'the permissions of the widget',
+                            nodoc: false
+                          },
+                        },
+                      }
+                    end
+
+                    it 'returns the formatted field schema' do
+                      expect(subject).to eq(
+                        'type' => 'object',
+                        'description' => 'Details about the widget.',
+                        'properties' => {
+                          'widget_name' => {
+                            'type' => 'string',
+                            'description' => 'The name of the widget.',
+                          },
+                          'widget_permissions' => {
+                            'type' => 'array',
+                            'description' => 'The permissions of the widget.',
+                            'items' => {
+                              'type' => 'string',
+                            }
+                          }
+                        }
+                      )
+                    end
+                  end
+
+                  context 'when formatting a multi nested hash field' do
+                    let(:field_configuration_tree) do
+                      {
+                        _config: {
+                          type: 'hash',
+                          info: 'Details about the widget',
+                        },
+                        widget_name: {
+                          _config: {
+                            required: true,
+                            type: 'string',
+                            info: 'the name of the widget',
+                            nodoc: false
+                          },
+                        },
+                        widget_permissions: {
+                          _config: {
+                            type: 'hash',
+                            info: 'the permissions of the widget',
+                            nodoc: false
+                          },
+                          can_edit: {
+                            _config: {
+                              type: 'boolean',
+                              info: 'can edit the widget',
+                              nodoc: false
+                            }
+                          }
+                        },
+                      }
+                    end
+
+                    it 'returns the formatted field schema' do
+                      expect(subject).to eq(
+                        'type' => 'object',
+                        'description' => 'Details about the widget.',
+                        'properties' => {
+                          'widget_name' => {
+                            'type' => 'string',
+                            'description' => 'The name of the widget.',
+                          },
+                          'widget_permissions' => {
+                            'type' => 'object',
+                            'description' => 'The permissions of the widget.',
+                            'properties' => {
+                              'can_edit' => {
+                                'type' => 'boolean',
+                                'description' => 'Can edit the widget.',
+                              }
+                            }
+                          }
+                        }
+                      )
+                    end
+                  end
+                end
+
+                context 'dynamic keys' do
+                  context 'when formatting a hash field' do
+                    let(:field_configuration_tree) do
+                      {
+                        _config: {
+                          type: 'hash',
+                          info: 'Dynamic keys hash.',
+                        },
+                        _dynamic_key: {
+                          _config: {
+                            nodoc: false,
+                            type: 'hash',
+                            dynamic_key: true,
+                            info: 'a dynamic description.'
+                          },
+                          blah: {
+                            _config: {
+                              nodoc: false,
+                              type: 'string',
+                            },
+                          },
+                        },
+                      }
+                    end
+
+                    it 'returns the formatted field schema' do
+                      expect(subject).to eq({
+                        'type' => 'object',
+                        'description' => 'Dynamic keys hash.',
+                        'additionalProperties' => {
+                          'type' => 'object',
+                          'description' => 'A dynamic description.',
+                          'properties' => {
+                            'blah' => {
+                              'type' => 'string',
+                            },
+                          },
+                        },
+                      })
+                    end
+                  end
+
+                  context 'when formatting a nested hash field' do
+                    let(:field_configuration_tree) do
+                      {
+                        _config: {
+                          type: 'hash',
+                          info: 'Dynamic keys hash.',
+                        },
+                        non_dynamic_key: {
+                          _config: {
+                            nodoc: false,
+                            type: 'hash',
+                            info: 'A non-dynamic description.'
+                          },
+                          non_dynamic_property: {
+                            _config: {
+                              nodoc: false,
+                              type: 'string',
+                            },
+                          },
+                        },
+                        _dynamic_key: {
+                          _config: {
+                            nodoc: false,
+                            type: 'hash',
+                            dynamic_key: true,
+                            info: 'A dynamic description.'
+                          },
+                          dynamic_property1: {
+                            _config: {
+                              nodoc: false,
+                              type: 'string',
+                            },
+                          },
+                          _dynamic_key: {
+                            _config: {
+                              nodoc: false,
+                              type: 'hash',
+                              dynamic_key: true,
+                              info: 'A 2nd dynamic description.'
+                            },
+                            _dynamic_key: {
+                              _config: {
+                                nodoc: false,
+                                type: 'string',
+                                dynamic_key: true,
+                                info: 'A dynamic string.'
+                              },
+                            },
+                            dynamic_property2: {
+                              _config: {
+                                nodoc: false,
+                                type: 'string',
+                              },
+                            },
+                          },
+                        },
+                      }
+                    end
+
+                    it 'returns the formatted field schema' do
+                      expect(subject).to eq({
+                        'type' => 'object',
+                        'description' => 'Dynamic keys hash.',
+                        'properties' => {
+                          'non_dynamic_key' => {
+                            'type' => 'object',
+                            'description' => 'A non-dynamic description.',
+                            'properties' => {
+                              'non_dynamic_property' => {
+                                'type' => 'string',
+                              }
+                            }
+                          },
+                        },
+                        'additionalProperties' => {
+                          'type' => 'object',
+                          'description' => 'A dynamic description.',
+                          'properties' => {
+                            'dynamic_property1' => {
+                              'type' => 'string',
+                            },
+                          },
+                          'additionalProperties' => {
+                            'type' => 'object',
+                            'description' => 'A 2nd dynamic description.',
+                            'properties' => {
+                              'dynamic_property2' => {
+                                'type' => 'string',
+                              },
+                            },
+                            'additionalProperties' => {
+                              'type' => 'string',
+                              'description' => 'A dynamic string.',
+                            },
+                          },
+                        },
+                      })
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/spec/brainstem/api_docs/formatters/open_api_specification/version_2/presenter_formatter_spec.rb

@@ -30,9 +30,10 @@ module Brainstem
 
             describe '#call' do
               before do
-                stub(presenter).format_title!  { title }
-                stub(presenter).format_fields! { fake_formatted_fields }
-                stub(presenter).valid_fields   { valid_fields }
+                stub(presenter).format_title!      { title }
+                stub(presenter).format_fields!     { fake_formatted_fields }
+                stub(presenter).valid_fields       { valid_fields }
+                stub(presenter).valid_associations { {} }
               end
 
               context 'when nodoc' do
@@ -146,6 +147,83 @@ module Brainstem
                 stub(presenter).conditionals { conditionals }
               end
 
+              context 'with associations present' do
+                context 'when association type is belongs_to or has_one' do
+                  before do
+                    presenter_class.associations do
+                      association :task, Task,
+                        type: :belongs_to
+
+                      association :user, User,
+                        response_key: :user_id,
+                        type: :has_one
+                    end
+                  end
+
+                  it 'outputs the foreign key in single formatted id' do
+                    subject.send(:format_fields!)
+
+                    expect(subject.definition).to have_key :properties
+                    expect(subject.definition[:properties]).to eq({
+                      'task_id' => { 'type' => 'string', 'description' => "`task_id` will only be included in the response if `task` is in the list of included associations. See <a href='#section/Includes'>include</a> section for usage." },
+                      'user_id' => { 'type' => 'string', 'description' => "`user_id` will only be included in the response if `user` is in the list of included associations. See <a href='#section/Includes'>include</a> section for usage." }
+                    })
+                  end
+                end
+
+                context 'when association type is has_many' do
+                  before do
+                    presenter_class.associations do
+                      association :task, Task,
+                        type: :has_many
+                    end
+                  end
+
+                  it 'outputs the foreign key in plural formatted id' do
+                    subject.send(:format_fields!)
+
+                    expect(subject.definition).to have_key :properties
+                    expect(subject.definition[:properties]).to eq({
+                      'task_ids' => {
+                        'type' => 'array',
+                        'description' => "`task_ids` will only be included in the response if `task` is in the list of included associations. See <a href='#section/Includes'>include</a> section for usage.",
+                        'items' => {
+                          'type' => 'string'
+                        },
+                      },
+                    })
+                  end
+                end
+
+                context 'when association is polymorphic' do
+                  before do
+                    presenter_class.associations do
+                      association :task, :polymorphic, polymorphic_classes: [User, Task]
+                    end
+                  end
+
+                  it 'outputs an object that contains an id and key' do
+                    subject.send(:format_fields!)
+
+                    expect(subject.definition).to have_key :properties
+                    expect(subject.definition[:properties]).to eq({
+                      'task_ref' => {
+                        'type' => 'object',
+                        'description' => "`task_ref` will only be included in the response if `task` is in the list of included associations. See <a href='#section/Includes'>include</a> section for usage.",
+                        'properties' => {
+                          'id' => {
+                            'type' => 'string'
+                          },
+                          'key' => {
+                            'type' => 'string'
+                          }
+                        }
+                      }
+                    })
+                  end
+                end
+              end
+
               context 'with fields present' do
                 describe 'branch node' do
                   context 'with single branch' do
@@ -165,7 +243,6 @@ module Brainstem
                         'sprockets' => {
                           'type' => 'object',
                           'properties' => {
-
                             'sprocket_name' => { 'type' => 'string', 'description' => 'Whatever.' }
                           }
                         }
@@ -225,6 +302,7 @@ module Brainstem
                         expect(subject.definition[:properties]).to eq({
                           'sprockets' => {
                             'type' => 'array',
+                            'description' => 'Parent.',
                             'items' => {
                               'type' => 'object',
                               'properties' => {
@@ -422,6 +500,40 @@ module Brainstem
                 end
               end
             end
+
+            describe '#sort_properties!' do
+              let(:presenter_class) do
+                Class.new(Brainstem::Presenter) do
+                  presents Workspace
+                end
+              end
+              let(:presenter) { Presenter.new(Object.new, const: presenter_class, target_class: 'Workspace') }
+              let(:conditionals) { {} }
+
+              before do
+                stub(presenter).conditionals { conditionals }
+
+                presenter_class.associations do
+                  association :user, User,
+                    response_key: :user_id,
+                    type: :has_one
+
+                  association :task, Task,
+                    type: :belongs_to
+                end
+              end
+
+              it 'correctly sorts the properties' do
+                subject.send(:format_fields!)
+                subject.send(:sort_properties!)
+
+                expect(subject.definition).to have_key :properties
+                expect(subject.definition[:properties]).to eq({
+                  'task_id' => { 'type' => 'string', 'description' => "`task_id` will only be included in the response if `task` is in the list of included associations. See <a href='#section/Includes'>include</a> section for usage." },
+                  'user_id' => { 'type' => 'string', 'description' => "`user_id` will only be included in the response if `user` is in the list of included associations. See <a href='#section/Includes'>include</a> section for usage." }
+                })
+              end
+            end
           end
         end
       end