brainstem 1.4.1 → 2.0.0

data/spec/brainstem/api_docs/presenter_spec.rb

@@ -21,7 +21,6 @@ module Brainstem
         end
       end
 
-
       describe "configured fields" do
         let(:lorem)  { "lorem ipsum dolor sit amet" }
         let(:const)  { Object.new }
@@ -38,7 +37,6 @@ module Brainstem
           end
         end
 
-
         describe "#nodoc?" do
           let(:config) { { nodoc: nodoc } }
 
@@ -57,7 +55,6 @@ module Brainstem
           end
         end
 
-
         describe "#title" do
           let(:config) { { title: { info: lorem, nodoc: nodoc } } }
 
@@ -76,14 +73,12 @@ module Brainstem
           end
         end
 
-
         describe "#brainstem_keys" do
           it "retrieves from the constant, array-izes, and sorts" do
             expect(subject.brainstem_keys).to eq [ "ipsum", "lorem" ]
           end
         end
 
-
         describe "#description" do
           context "with description" do
             let(:config) { { description: { info: lorem, nodoc: nodoc } } }
@@ -110,7 +105,6 @@ module Brainstem
           end
         end
 
-
         describe "#valid_fields" do
           let(:presenter_class) do
             Class.new(Brainstem::Presenter) do
@@ -240,6 +234,64 @@ module Brainstem
           end
         end
 
+        describe "#optional_field_names" do
+          let(:presenter_class) do
+            Class.new(Brainstem::Presenter) do
+              presents Workspace
+
+              fields do
+                field :mandatory_field, :string, dynamic: lambda { "new_field value" }
+                field :optional_top_field, :string, dynamic: lambda { "new_field value" }, optional: true
+                field :nodoc_optional_top_field, :string, dynamic: lambda { "new_field value" }, optional: true, nodoc: true
+
+                fields :optional_block_field, :hash, optional: true do
+                  field :leaf_field_1, :string
+                end
+
+                fields :nodoc_optional_block_field, :hash, optional: true, nodoc: true do
+                  field :leaf_field_2, :string
+                end
+
+                fields :nodoc_block_field, :hash, nodoc: true do
+                  field :optional_field_nodoc_block_field, :string, optional: true
+                end
+
+                fields :block_field_with_optional_fields, :hash do
+                  fields :optional_double_nested_field, :hash, optional: true do
+                    field :leaf_field_3, :string
+                  end
+
+                  fields :double_nested_field, :hash do
+                    field :leaf_field_4, :string
+                    field :optional_leaf_field, :string, optional: true
+                    field :nodoc_optional_leaf_field, :string, optional: true, nodoc: true
+                  end
+                end
+              end
+            end
+          end
+
+          subject { described_class.new(atlas, target_class: 'Workspace', const: presenter_class).optional_field_names }
+
+          before do
+            stub(atlas).find_by_class(anything) { nil }
+          end
+
+          it 'includes optional top level fields if nodoc is false' do
+            expect(subject).to include('optional_top_field')
+            expect(subject).to_not include('nodoc_optional_top_field')
+          end
+
+          it 'includes optional block fields if nodoc is false' do
+            expect(subject).to include('optional_block_field', 'optional_double_nested_field')
+            expect(subject).to_not include('nodoc_optional_block_field')
+          end
+
+          it 'includes optional leaf fields of block fields if nodoc is false' do
+            expect(subject).to include('optional_leaf_field')
+            expect(subject).to_not include('nodoc_optional_leaf_field', 'optional_field_nodoc_block_field')
+          end
+        end
 
         describe "#valid_filters" do
           let(:info)        { lorem }
@@ -267,7 +319,6 @@ module Brainstem
           end
         end
 
-
         describe "#documentable_filter?" do
           let(:info)   { lorem }
           let(:filter) { { nodoc: nodoc, info: info } }
@@ -309,7 +360,6 @@ module Brainstem
           end
         end
 
-
         describe "#valid_sort_orders" do
           let(:config) { { sort_orders: { title: { nodoc: true }, date: {} } } }
 
@@ -319,7 +369,6 @@ module Brainstem
           end
         end
 
-
         describe "#valid_associations" do
           let(:info)        { lorem }
           let(:association) { Object.new }
@@ -346,7 +395,6 @@ module Brainstem
           end
         end
 
-
         describe "#documentable_association?" do
           let(:desc)        { lorem }
           let(:association) { OpenStruct.new(options: { nodoc: nodoc }, description: desc ) }
@@ -388,7 +436,6 @@ module Brainstem
           end
         end
 
-
         describe "#conditionals" do
           let(:config) { { conditionals: { thing: :other_thing } } }
 
@@ -405,7 +452,6 @@ module Brainstem
           end
         end
 
-
         describe "#default_sort_field" do
           context "when has default sort order" do
             let(:config) { { default_sort_order: "alphabetical:asc" } }
@@ -422,7 +468,6 @@ module Brainstem
           end
         end
 
-
         describe "#default_sort_direction" do
           context "when has default sort order" do
             let(:config) { { default_sort_order: "alphabetical:asc" } }
@@ -485,7 +530,6 @@ module Brainstem
         end
       end
 
-
       describe "#suggested_filename" do
         before do
           stub(target_class).to_s { "Abc" }
@@ -504,7 +548,6 @@ module Brainstem
         end
       end
 
-
       describe "#suggested_filename_link" do
         before do
           stub(target_class).to_s { "Abc" }
@@ -523,7 +566,6 @@ module Brainstem
         end
       end
 
-
       describe "#relative_path_to_presenter" do
         let(:presenter) {
           mock!
@@ -538,7 +580,6 @@ module Brainstem
         end
       end
 
-
       describe "#link_for_association" do
         let(:presenter)    { Object.new }
         let(:target_class) { Class.new }
@@ -578,7 +619,6 @@ module Brainstem
         end
       end
 
-
       it_behaves_like "formattable"
       it_behaves_like "atlas taker"
     end

data/spec/brainstem/api_docs/resolver_spec.rb

@@ -49,7 +49,6 @@ module Brainstem
         end
       end
 
-
       describe "#find_presenter_from_target_class" do
         let(:klass)             { Class.new }
         let(:presenter_const)   { Class.new }

data/spec/brainstem/api_docs/sinks/controller_presenter_multifile_sink_spec.rb

@@ -33,13 +33,11 @@ module Brainstem
           end
         end
 
-
         context "presenters" do
           before do
             stub(subject).write_controller_files
           end
 
-
           it "writes each presenter to its own file" do
             stub(atlas).presenters
               .stub!

data/spec/brainstem/api_docs/sinks/open_api_specification_sink_spec.rb

@@ -0,0 +1,371 @@
+require 'spec_helper'
+require 'brainstem/api_docs/sinks/open_api_specification_sink'
+require 'brainstem/api_docs/formatters/open_api_specification/version_2/info_formatter'
+require 'brainstem/api_docs/formatters/open_api_specification/version_2/security_definitions_formatter'
+require 'brainstem/api_docs/formatters/open_api_specification/version_2/tags_formatter'
+
+module Brainstem
+  module ApiDocs
+    module Sinks
+      describe OpenApiSpecificationSink do
+        let(:write_method)    { Object.new }
+        let(:atlas)           { Object.new }
+        let(:options)         { default_options }
+        let(:default_options) {
+          {
+            api_version:  '2.0.0',
+            format:       :oas_v2,
+            write_method: write_method,
+            write_path:   './',
+          }
+        }
+
+        subject { described_class.new(options) }
+
+        context "writing the specification" do
+          before do
+            mock(subject).write_info_object!
+            mock(subject).write_presenter_definitions!
+            mock(subject).write_error_definitions!
+            mock(subject).write_endpoint_definitions!
+            mock(subject).write_tag_definitions!
+            mock(subject).write_security_definitions!
+
+            mock.proxy(subject).write_spec_to_file!
+          end
+
+          it "calls the write method" do
+            mock(write_method).call('./specification.yml', anything)
+
+            subject << atlas
+          end
+
+          context "when a filename pattern is specified" do
+            let(:options) {
+              default_options.merge(
+                api_version: "1.1.0",
+                oas_filename_pattern: "specification_{{version}}.{{extension}}",
+                output_extension: "json"
+              )
+            }
+
+            it "calls the write method with customized filename" do
+              mock(write_method).call('./specification_1.1.0.json', anything)
+
+              subject << atlas
+            end
+          end
+
+          context "when a output extension is specified" do
+            let(:options) { default_options.merge(output_extension: output_extension) }
+
+            context "when valid extension is specified" do
+              let(:output_extension) { 'JSON' }
+
+              it "calls the write method with the correct file extension" do
+                mock(write_method).call('./specification.json', anything)
+
+                subject << atlas
+              end
+            end
+
+            context "when unsupported extension is specified" do
+              let(:output_extension) { 'JSON' }
+
+              it "raises an error" do
+                expect { subject << atlas }.to raise_error(StandardError)
+              end
+            end
+          end
+        end
+
+        describe "specification" do
+          let(:generated_data) { { 'sprockets' => { 'type' => 'object' } } }
+
+          before do
+            mock.proxy(subject).write_spec_to_file!
+          end
+
+          it "writes the data returned from the info formatter" do
+            mock(subject).write_presenter_definitions!
+            mock(subject).write_error_definitions!
+            mock(subject).write_endpoint_definitions!
+            mock(subject).write_tag_definitions!
+            mock(subject).write_security_definitions!
+
+            mock.proxy(subject).write_info_object!
+            mock.proxy
+              .any_instance_of(Brainstem::ApiDocs::Formatters::OpenApiSpecification::Version2::InfoFormatter)
+              .call { generated_data }
+            mock(write_method).call('./specification.yml', generated_data.to_yaml)
+
+            subject << atlas
+          end
+
+          context "when generating schema definitions" do
+            let(:generated_data) {
+              [
+                { 'widgets'   => { 'type' => 'object' } },
+                { 'sprockets' => { 'type' => 'object' } }
+              ]
+            }
+            let(:expected_yaml) {
+              {
+                'definitions' => {
+                  'sprockets' => { 'type' => 'object' },
+                  'widgets'   => { 'type' => 'object' }
+                }
+              }.to_yaml
+            }
+
+            it "writes presenter definitions" do
+              mock(subject).write_info_object!
+              mock(subject).write_error_definitions!
+              mock(subject).write_endpoint_definitions!
+              mock(subject).write_tag_definitions!
+              mock(subject).write_security_definitions!
+
+              mock.proxy(subject).write_presenter_definitions!
+              stub(atlas).presenters.stub!.formatted(:oas_v2) { generated_data }
+              mock(write_method).call('./specification.yml', expected_yaml)
+
+              subject << atlas
+            end
+          end
+
+          context "when generating error definitions" do
+            let(:generated_data) {
+              [
+                { 'widgets'   => { 'type' => 'object' } },
+                { 'sprockets' => { 'type' => 'object' } }
+              ]
+            }
+            let(:expected_yaml) {
+              {
+                'definitions' => {
+                  'sprockets' => { 'type' => 'object' },
+                  'widgets'   => { 'type' => 'object' },
+                  'Error'     => {
+                    'type' => 'object',
+                    'properties' => {
+                      'type'    => { 'type' => 'string' },
+                      'message' => { 'type' => 'string' },
+                    }
+                  },
+                  'Errors' => {
+                    'type' => 'object',
+                    'properties' => {
+                      'errors' => {
+                        'type'  => 'array',
+                        'items' => {
+                          '$ref' => '#/definitions/Error'
+                        }
+                      }
+                    }
+                  },
+                }
+              }.to_yaml
+            }
+
+            it "writes error definitions" do
+              mock(subject).write_info_object!
+              mock(subject).write_endpoint_definitions!
+              mock(subject).write_tag_definitions!
+              mock(subject).write_security_definitions!
+
+              mock.proxy(subject).write_presenter_definitions!
+              mock.proxy(subject).write_error_definitions!
+
+              stub(atlas).presenters.stub!.formatted(:oas_v2) { generated_data }
+              mock(write_method).call('./specification.yml', expected_yaml)
+
+              subject << atlas
+            end
+          end
+
+          context "when generating endpoint definitions" do
+            let(:generated_data) {
+              [
+                { '/widgets'   => { 'get'  => { 'type' => 'object' } } },
+                { '/sprockets' => { 'post' => { 'type' => 'object' } } }
+              ]
+            }
+            let(:expected_yaml) {
+              {
+                'paths' => {
+                  '/sprockets' => { 'post' => { 'type' => 'object' } },
+                  '/widgets'   => { 'get'  => { 'type' => 'object' } }
+                }
+              }.to_yaml
+            }
+
+            it "writes endpoint definitions" do
+              mock(subject).write_info_object!
+              mock(subject).write_error_definitions!
+              mock(subject).write_presenter_definitions!
+              mock(subject).write_tag_definitions!
+              mock(subject).write_security_definitions!
+              mock.proxy(subject).write_endpoint_definitions!
+
+              stub(atlas).controllers.stub!.formatted(:oas_v2) { generated_data }
+              mock(write_method).call('./specification.yml', expected_yaml)
+
+              subject << atlas
+            end
+          end
+
+          context "when generating tag definitions" do
+            let(:documentable_controller_Z) {
+              OpenStruct.new(
+                name:        'controller_Z',
+                description: 'controller_Z desc',
+                endpoints:   OpenStruct.new(only_documentable: [1, 2]),
+                tag:         'Tag Z',
+                tag_groups:  ['Group Z'],
+              )
+            }
+            let(:documentable_controller_A) {
+              OpenStruct.new(
+                name:        'controller_A',
+                description: 'controller_A desc',
+                endpoints:   OpenStruct.new(only_documentable: [1, 2]),
+                tag:         'Tag A',
+                tag_groups:  ['Group Z', 'Group A'],
+              )
+            }
+            let(:controllers) {
+              [
+                documentable_controller_Z,
+                documentable_controller_A,
+              ]
+            }
+            let(:expected_yaml) {
+              {
+                'tags' => [
+                  { 'name' => 'Tag A', 'description' => 'Controller_A desc.' },
+                  { 'name' => 'Tag Z', 'description' => 'Controller_Z desc.' }
+                ],
+                'x-tagGroups' => [
+                  { 'name' => 'Group A', 'tags' => ['Tag A'] },
+                  { 'name' => 'Group Z', 'tags' => ['Tag A', 'Tag Z'] }
+                ],
+              }.to_yaml
+            }
+            let(:ignore_tagging) { false }
+            let(:options) { default_options.merge(ignore_tagging: ignore_tagging) }
+
+            it "writes endpoint definitions" do
+              mock(subject).write_info_object!
+              mock(subject).write_error_definitions!
+              mock(subject).write_presenter_definitions!
+              mock(subject).write_endpoint_definitions!
+              mock(subject).write_security_definitions!
+
+              mock.proxy(subject).write_tag_definitions!
+              stub(atlas).controllers { controllers }
+              mock(write_method).call('./specification.yml', expected_yaml)
+
+              subject << atlas
+            end
+          end
+
+          context "when generating security definitions" do
+            let(:expected_yaml) {
+              {
+                'securityDefinitions' => {
+                  'api_key' => {
+                    'type' => 'apiKey',
+                    'name' => 'api_key',
+                    'in'   => 'header'
+                  },
+                  'petstore_auth' => {
+                    'type'             => 'oauth2',
+                    'authorizationUrl' => 'http://petstore.swagger.io/oauth/dialog',
+                    'flow'             => 'implicit',
+                    'scopes'           => {
+                      'write:pets' => 'modify pets in your account',
+                      'read:pets'  => 'read your pets'
+                    }
+                  }
+                }
+              }.to_yaml
+            }
+
+            it "writes endpoint definitions" do
+              mock(subject).write_info_object!
+              mock(subject).write_error_definitions!
+              mock(subject).write_presenter_definitions!
+              mock(subject).write_tag_definitions!
+              mock(subject).write_endpoint_definitions!
+
+              mock.proxy(subject).write_security_definitions!
+              stub(atlas).controllers.stub!.formatted(:oas_v2) { generated_data }
+              mock(write_method).call('./specification.yml', expected_yaml)
+
+              subject << atlas
+            end
+          end
+        end
+
+        describe "versioning" do
+          let(:options) {
+            {
+              api_version:  api_version,
+              write_method: write_method,
+              write_path:   './'
+            }
+          }
+
+          before do
+            stub(subject).write_spec_to_file!
+          end
+
+          context "when version is specified" do
+            let(:api_version) { '2.1.1' }
+
+            it "returns the specified version" do
+              expect(subject.send(:formatted_version)).to eq(api_version)
+            end
+          end
+
+          context "when version is not specified" do
+            let(:api_version) { nil }
+
+            it "returns the default version" do
+              expect(subject.send(:formatted_version)).to eq('1.0.0')
+            end
+          end
+        end
+
+        describe "suggested_filename" do
+          let(:options) {
+            default_options.merge(
+              api_version: '1.1.1',
+              oas_filename_pattern: oas_filename_pattern
+            )
+          }
+
+          before do
+            stub(subject).write_spec_to_file!
+          end
+
+          context "when version is specified" do
+            let(:oas_filename_pattern) { "{{version}}.{{extension}}" }
+
+            it "returns the customized filename" do
+              expect(subject.send(:suggested_filename)).to eq("1.1.1.yml")
+            end
+          end
+
+          context "when version is not specified" do
+            let(:oas_filename_pattern) { nil }
+
+            it "returns the default filename" do
+              expect(subject.send(:suggested_filename)).to eq('specification.yml')
+            end
+          end
+        end
+      end
+    end
+  end
+end