brainstem 1.4.1 → 2.0.0

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

@@ -0,0 +1,89 @@
+require 'spec_helper'
+require 'brainstem/api_docs/formatters/open_api_specification/version_2/info_formatter'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module OpenApiSpecification
+        module Version2
+          describe InfoFormatter do
+            let(:version) { 2 }
+
+            subject { described_class.new(version: version) }
+
+            describe 'call' do
+              before do
+                mock.proxy(subject).format_swagger_object!
+                mock.proxy(subject).format_info_object!
+              end
+
+              it 'includes the correct top level attributes' do
+                output = subject.call
+
+                expect(output.keys).to match_array(%w(swagger host basePath schemes consumes produces info))
+              end
+            end
+
+            describe 'format_swagger_object!' do
+              before do
+                mock.proxy(subject).host
+                mock.proxy(subject).schemes
+                mock.proxy(subject).consumes
+                mock.proxy(subject).produces
+              end
+
+              it 'includes the correct attributes' do
+                swagger_object = subject.send(:format_swagger_object!)
+
+                expect(swagger_object.keys).to match_array(%w(swagger host basePath schemes consumes produces))
+              end
+            end
+
+            describe 'format_info_object!' do
+              before do
+                mock.proxy(subject).version
+                mock.proxy(subject).title
+                mock.proxy(subject).description
+                mock.proxy(subject).terms_of_service
+                mock.proxy(subject).contact_object
+                mock.proxy(subject).license_object
+              end
+
+              it 'includes the top level info key' do
+                output = subject.send(:format_info_object!)
+
+                expect(output.keys).to eq(%w(info))
+              end
+
+              it 'includes the correct attributes' do
+                info_object = subject.send(:format_info_object!)['info']
+
+                expect(info_object.keys).to match_array(%w(version title description termsOfService contact license))
+              end
+
+              context 'when version is specified' do
+                let(:version) { 2 }
+
+                it 'sets the version attribute in the info object to the given value' do
+                  info_object = subject.send(:format_info_object!)['info']
+
+                  expect(info_object['version']).to eq(version)
+                end
+              end
+
+              context 'when version is not specified' do
+                let(:version) { nil }
+
+                it 'defaults the version attribute in the info object to "1.0"' do
+                  info_object = subject.send(:format_info_object!)['info']
+
+                  expect(info_object['version']).to eq('1.0')
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,430 @@
+require 'spec_helper'
+require 'brainstem/api_docs/formatters/open_api_specification/version_2/presenter_formatter'
+require 'brainstem/api_docs/presenter'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module OpenApiSpecification
+        module Version2
+          describe PresenterFormatter do
+            let(:presenter_args)        { {} }
+            let(:extra_presenter_args)  { {} }
+            let(:presenter)             { Presenter.new(presenter_args.merge(extra_presenter_args)) }
+            let(:nodoc)                 { false }
+            let(:title)                 { 'Sprocket' }
+            let(:presented_class)       { 'Sprocket' }
+            let(:lorem)                 { 'Best description ever' }
+            let(:valid_fields)          { { title: OpenStruct.new(name: :title, type: :string, options: {}) } }
+            let(:fake_formatted_fields) { { "title" => {"type" => "string"}}}
+
+            subject { described_class.new(presenter) }
+
+            before do
+              stub(presenter).nodoc?                           { nodoc }
+              stub(presenter).target_class                     { presented_class }
+              stub(presenter).description                      { lorem }
+              stub(presenter).title                            { title }
+              stub(presenter).contextual_documentation(:title) { title }
+            end
+
+            describe '#call' do
+              before do
+                stub(presenter).format_title!  { title }
+                stub(presenter).format_fields! { fake_formatted_fields }
+                stub(presenter).valid_fields   { valid_fields }
+              end
+
+              context 'when nodoc' do
+                let(:nodoc) {true}
+
+                before do
+                  any_instance_of(described_class) do |instance|
+                    dont_allow(instance).format_title!
+                    dont_allow(instance).format_description!
+                    dont_allow(instance).format_type!
+                    dont_allow(instance).format_fields!
+                  end
+                end
+
+                it 'returns an empty output' do
+                  expect(subject.call).to be {}
+                end
+              end
+
+              context 'when not nodoc' do
+                let(:nodoc) {false}
+
+                before do
+                  any_instance_of(described_class) do |instance|
+                    mock.proxy(instance).format_title!
+                    mock.proxy(instance).format_description!
+                    mock.proxy(instance).format_type!
+                    mock.proxy(instance).format_fields!
+                  end
+                end
+
+                it 'formats data' do
+                  expect(subject.call).to_not be_empty
+                end
+
+                it 'top level key in the output is set to the presented class' do
+                  subject.call
+
+                  expect(subject.output.keys).to eq([presented_class])
+                  expect(subject.output[presented_class].keys).to eq(%w(title description type properties))
+                  expect(subject.output[presented_class]['title']).to eq(title)
+                  expect(subject.output[presented_class]['description']).to eq("#{lorem}.")
+                  expect(subject.output[presented_class]['type']).to eq('object')
+                  expect(subject.output[presented_class]['properties']).to eq(fake_formatted_fields)
+                end
+              end
+            end
+
+            describe '#format_title!' do
+              before do
+                stub(presenter).valid_fields { valid_fields }
+              end
+
+              context 'when the presenter has a title' do
+                let(:title) { 'Sprockets are cool, I think' }
+
+                it 'returns the title' do
+                  subject.send(:format_title!)
+
+                  expect(subject.definition).to have_key(:title)
+                  expect(subject.definition[:title]).to eq title
+                end
+              end
+
+              context 'when the presenter does not have a title' do
+                let(:title) { nil }
+
+                it 'returns formatted key' do
+                  subject.send(:format_title!)
+
+                  expect(subject.definition).to have_key(:title)
+                  expect(subject.definition[:title]).to eq presented_class
+                end
+              end
+            end
+
+            describe '#format_description' do
+              context 'when the presenter has a description' do
+                let(:lorem) {'                  way over here   '}
+
+                it 'returns the string-ized stripped description' do
+                  subject.send(:format_description!)
+
+                  expect(subject.definition).to have_key(:description)
+                  expect(subject.definition[:description]).to eq 'Way over here.'
+                end
+              end
+
+              context 'when the presenter does not have a description' do
+                let(:lorem) { nil }
+
+                it 'returns an empy string' do
+                  subject.send(:format_description!)
+
+                  expect(subject.definition).to have_key(:description)
+                  expect(subject.definition[:description]).to eq ''
+                end
+              end
+            end
+
+            describe '#format_fields!' 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 }
+              end
+
+              context 'with fields present' do
+                describe 'branch node' do
+                  context 'with single branch' do
+                    before do
+                      presenter_class.fields do
+                        fields :sprockets do
+                          field :sprocket_name, :string, via: :name, info: 'Whatever.'
+                        end
+                      end
+                    end
+
+                    it 'outputs the name of sub-branch as a property of the parent' do
+                      subject.send(:format_fields!)
+
+                      expect(subject.definition).to have_key :properties
+                      expect(subject.definition[:properties]).to eq({
+                        'sprockets' => {
+                          'type' => 'object',
+                          'properties' => {
+
+                            'sprocket_name' => { 'type' => 'string', 'description' => 'Whatever.' }
+                          }
+                        }
+                      })
+                    end
+                  end
+
+                  context 'with sub-branch of type hash' do
+                    before do
+                      presenter_class.fields do
+                        fields :sprockets do
+                          fields :sub_sprocket do
+                            field :sprocket_name, :string, via: :name, info: 'Whatever.'
+                          end
+                        end
+                      end
+                    end
+
+                    it 'outputs the name of sub-branches as a properties of the its parent' do
+                      subject.send(:format_fields!)
+
+                      expect(subject.definition).to have_key :properties
+                      expect(subject.definition[:properties]).to eq({
+                        'sprockets' => {
+                          'type' => 'object',
+                          'properties' => {
+
+                            'sub_sprocket' => {
+                              'type' => 'object',
+                              'properties' => {
+
+                                'sprocket_name' => { 'type' => 'string', 'description' => 'Whatever.' }
+                              }
+                            }
+                          }
+                        }
+                      })
+                    end
+                  end
+
+                  context 'with sub branch of type array' do
+                    xcontext 'when type of list items is an array'
+
+                    context 'when type of list items is a hash' do
+                      before do
+                        presenter_class.fields do
+                          fields :sprockets, :array, item_type: 'hash', info: 'parent' do
+                            field :sprocket_name, :string, via: :name, info: 'Whatever.'
+                          end
+                        end
+                      end
+
+                      it 'outputs the name of sub-branches as a properties of the its parent' do
+                        subject.send(:format_fields!)
+
+                        expect(subject.definition).to have_key :properties
+                        expect(subject.definition[:properties]).to eq({
+                          'sprockets' => {
+                            'type' => 'array',
+                            'items' => {
+                              'type' => 'object',
+                              'properties' => {
+
+                                'sprocket_name' => { 'type' => 'string', 'description' => 'Whatever.' }
+                              }
+                            }
+                          }
+                        })
+                      end
+                    end
+                  end
+                end
+
+                describe 'leaf node' do
+                  context 'if it is not conditional' do
+                    before do
+                      presenter_class.fields do
+                        field :sprocket_name, :string, info: 'whatever'
+                        field :sprocket_size, :integer
+                      end
+                    end
+
+                    it 'outputs each field as a list item' do
+                      subject.send(:format_fields!)
+
+                      expect(subject.definition).to have_key :properties
+                      expect(subject.definition[:properties]).to eq({
+                        'sprocket_name' => { 'type' => 'string', 'description' => 'Whatever.' },
+                        'sprocket_size' => { 'type' => 'integer', 'format' => 'int32' }
+                      })
+                    end
+
+                    describe 'optional' do
+                      let(:formatted_description) { subject.definition[:properties]['sprocket_name']['description'] }
+
+                      context 'when true' do
+                        before do
+                          presenter_class.fields do
+                            field :sprocket_name, :string, info: 'Whatever.', optional: true
+                            field :sprocket_size, :integer
+                          end
+                        end
+
+                        it 'says so' do
+                          subject.send(:format_fields!)
+
+                          expect(subject.definition).to have_key :properties
+                          expect(formatted_description).to include 'Only returned when requested'
+                        end
+                      end
+
+                      context 'when false' do
+                        before do
+                          presenter_class.fields do
+                            field :sprocket_name, :string, info: 'Whatever.', optional: false
+                            field :sprocket_size, :integer
+                          end
+                        end
+
+                        it 'says nothing' do
+                          subject.send(:format_fields!)
+
+                          expect(subject.definition).to have_key :properties
+                          expect(formatted_description).to_not include 'Only returned when requested'
+                        end
+                      end
+                    end
+
+                    describe 'description' do
+                      context 'when present' do
+                        before do
+                          presenter_class.fields do
+                            field :sprocket_name, :string, info: 'Whatever.'
+                            field :sprocket_size, :integer
+                          end
+                        end
+
+                        it 'outputs the description' do
+                          subject.send(:format_fields!)
+
+                          expect(subject.definition).to have_key :properties
+                          expect(subject.definition[:properties]['sprocket_name']['description']).to eq('Whatever.')
+                        end
+                      end
+
+                      context 'when absent' do
+                        before do
+                          presenter_class.fields do
+                            field :sprocket_name, :string
+                            field :sprocket_size, :integer
+                          end
+                        end
+
+                        it 'does not include the description' do
+                          subject.send(:format_fields!)
+
+                          expect(subject.definition).to have_key :properties
+                          expect(subject.definition[:properties]['sprocket_name']).to_not have_key('description')
+                        end
+                      end
+                    end
+                  end
+
+                  context 'if it is conditional' do
+                    let(:formatted_description) {subject.definition[:properties]['sprocket_name']['description']}
+
+                    before do
+                      presenter_class.fields do
+                        field :sprocket_name, :string, info: 'whatever', if: [:it_is_a_friday]
+                      end
+                    end
+
+                    context 'if nodoc' do
+                      let(:conditionals) {
+                        {
+                          :it_is_a_friday => OpenStruct.new(
+                            description: nil,
+                            name:        :it_is_a_friday,
+                            type:        :request,
+                            options:     { nodoc: true }
+                          )
+                        }
+                      }
+
+                      it 'does not include the conditional' do
+                        subject.send(:format_fields!)
+
+                        expect(formatted_description).not_to include 'Visible when'
+                      end
+                    end
+
+                    context 'if not nodoc' do
+                      context 'if the conditional has a description' do
+                        let(:conditionals) {
+                          {
+                            :it_is_a_friday => OpenStruct.new(
+                              description: 'It is a friday',
+                              name:        :it_is_a_friday,
+                              type:        :request,
+                              options:     {},
+                            )
+                          }
+                        }
+
+                        it 'includes the conditional' do
+                          subject.send(:format_fields!)
+
+                          expect(formatted_description).to include 'Visible when it is a friday.'
+                        end
+                      end
+
+                      context 'if the condition doesn\'t have a description' do
+                        let(:conditionals) {
+                          {
+                            :it_is_a_friday => OpenStruct.new(
+                              description: nil,
+                              name:        :it_is_a_friday,
+                              type:        :request,
+                              options:     {},
+                            )
+                          }
+                        }
+
+                        it 'does not include the conditional' do
+                          subject.send(:format_fields!)
+
+                          expect(formatted_description).not_to include 'Visible when'
+                        end
+                      end
+                    end
+                  end
+
+                  context 'when invalid type specified' do
+                    before do
+                      presenter_class.fields do
+                        field :sprocket_name, :invalid
+                      end
+                    end
+
+                    it 'raises an error' do
+                      expect { subject.send(:format_fields!) }.to raise_error(StandardError)
+                    end
+                  end
+                end
+              end
+
+              context 'with no fields' do
+                let(:valid_fields) {{}}
+
+                it 'outputs that no fields were listed' do
+                  subject.send(:format_fields!)
+
+                  expect(subject.definition[:properties]).to be_nil
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end