brainstem 1.4.1 → 2.0.0

data/spec/brainstem/api_docs/formatters/abstract_formatter_spec.rb

@@ -17,13 +17,11 @@ module Brainstem
           end
         end
 
-
         describe "#call" do
           it "is not implemented" do
             expect { subject.call }.to raise_error NotImplementedError
           end
         end
-
       end
     end
   end

data/spec/brainstem/api_docs/formatters/markdown/controller_formatter_spec.rb

@@ -56,7 +56,6 @@ module Brainstem
             let(:default_config) { {} }
             let(:configuration)  { { _default: default_config } }
 
-
             describe "#format_title!" do
               it "outputs it as an h2" do
                 stub(controller).title { lorem }

data/spec/brainstem/api_docs/formatters/markdown/endpoint_collection_formatter_spec.rb

@@ -40,7 +40,6 @@ module Brainstem
             end
           end
 
-
           describe "formatting" do
             describe "#format_endpoints!" do
               it "joins each documentable endpoint" do
@@ -50,7 +49,6 @@ module Brainstem
               end
             end
 
-
             describe "#format_zero_text!" do
               it "appends the zero text" do
                 subject.send(:format_zero_text!)
@@ -59,7 +57,6 @@ module Brainstem
             end
           end
 
-
           describe "#all_formatted_endpoints" do
             it "retrieves all formatted endpoints" do
               documentable_collection = Object.new
@@ -77,8 +74,6 @@ module Brainstem
             end
           end
         end
-
-
       end
     end
   end

data/spec/brainstem/api_docs/formatters/markdown/endpoint_formatter_spec.rb

@@ -18,6 +18,7 @@ module Brainstem
           describe "#call" do
             before do
               stub(endpoint).nodoc? { nodoc }
+              stub(endpoint).custom_response { {} }
             end
 
             context "when it is nodoc" do
@@ -78,7 +79,6 @@ module Brainstem
               end
             end
 
-
             describe "#format_description!" do
               context "when present" do
                 before do
@@ -106,7 +106,6 @@ module Brainstem
               end
             end
 
-
             describe "#format_endpoint!" do
               let(:endpoint_args) { { http_methods: %w(get post), path: "/widgets(.:format)" } }
 
@@ -127,7 +126,6 @@ module Brainstem
               end
             end
 
-
             describe "#format_params!" do
               let(:const) do
                 Class.new do
@@ -316,15 +314,103 @@ module Brainstem
             end
 
             describe "#format_presents!" do
-              let(:presenter) { Object.new }
+              context "when has a custom response" do
+                before do
+                  stub(endpoint).custom_response { true }
+                  stub(endpoint).custom_response_configuration_tree { custom_response_configuration }
+                end
 
-              before do
-                stub(endpoint).presenter_title { "Sprocket Widget" }
-                stub(endpoint).relative_presenter_path_from_controller(:markdown) { "../../sprocket_widget.markdown" }
+                context "when the response type is a hash" do
+                  let(:custom_response_configuration) do
+                    {
+                      '_config' => {
+                        'type' => 'hash',
+                      },
+                      'widget_name' => {
+                        '_config' => {
+                          'type' => 'string',
+                          'info' => 'the name of the widget',
+                          'nodoc' => false
+                        },
+                      },
+                      'widget_permission' => {
+                        '_config' => {
+                          'type' => 'hash',
+                          'nodoc' => false
+                        },
+                        'can_edit' => {
+                          '_config' => {
+                            'type' => 'boolean',
+                            'info' => 'can edit the widget',
+                            'nodoc' => false
+                          },
+                        }
+                      },
+                    }.with_indifferent_access
+                  end
+
+                  it "formats the custom response" do
+                    subject.send(:format_presents!)
+
+                    output = subject.output
+                    expect(output).to include("The resulting JSON is a hash with the following properties\n\n")
+                    expect(output).to include("- `widget_name` (`String`) - the name of the widget\n")
+                    expect(output).to include("- `widget_permission` (`Hash`)\n")
+                    expect(output).to include("    - `can_edit` (`Boolean`) - can edit the widget\n")
+                  end
+                end
+
+                context "when the response is an array" do
+                  let(:custom_response_configuration) do
+                    {
+                      '_config' => {
+                        'type' => 'array',
+                        'item_type' => 'hash',
+                      },
+                      'widget_name' => {
+                        '_config' => {
+                          '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' => 'boolean',
+                            'info' => 'can edit the widget',
+                            'nodoc' => false
+                          },
+                        }
+                      },
+                    }.with_indifferent_access
+                  end
+
+                  it "formats the custom response" do
+                    subject.send(:format_presents!)
+
+                    output = subject.output
+                    expect(output).to include "The resulting JSON is an array of objects with the following properties\n\n"
+                    expect(output).to include("- `widget_name` (`String`) - the name of the widget\n")
+                    expect(output).to include("- `widget_permissions` (`Array<Hash>`) - the permissions of the widget\n")
+                    expect(output).to include("    - `can_edit` (`Boolean`) - can edit the widget\n")
+                  end
+                end
               end
 
-              context "when present" do
+              context "when custom response is absent and presenter is present" do
+                let(:presenter) { Object.new }
+
                 before do
+                  stub(endpoint).custom_response { false }
+                  stub(endpoint).presenter_title { "Sprocket Widget" }
+                  stub(endpoint).relative_presenter_path_from_controller(:markdown) { "../../sprocket_widget.markdown" }
                   stub(endpoint).presenter { presenter }
                 end
 

data/spec/brainstem/api_docs/formatters/markdown/helper_spec.rb

@@ -32,21 +32,18 @@ module Brainstem
             end
           end
 
-
           describe "#md_p" do
             it "appends two newlines" do
               expect(subject.md_p(lipsum)).to eq(lipsum + "\n\n")
             end
           end
 
-
           describe "#md_strong" do
             it "wraps the text in asterisk pairs" do
               expect(subject.md_strong("Popeye")).to eq "**Popeye**"
             end
           end
 
-
           describe "#md_code" do
             it "renders the code between backtick blocks" do
               expect(subject.md_code('var my_var = 1;')).to eq "```\nvar my_var = 1;\n```\n\n"
@@ -57,14 +54,12 @@ module Brainstem
             end
           end
 
-
           describe "#md_inline_code" do
             it "renders the code between single backticks" do
               expect(subject.md_inline_code('my_var')).to eq "`my_var`"
             end
           end
 
-
           describe "#md_ul" do
             it "evaluates the block given to it in the instance's context" do
               mock(subject).md_h1('hello') { }
@@ -76,7 +71,6 @@ module Brainstem
             end
           end
 
-
           describe "#md_li" do
             it "renders the text after a dash-space with a newline" do
               expect(subject.md_li("text")).to eq "- text\n"
@@ -87,14 +81,12 @@ module Brainstem
             end
           end
 
-
           describe "#md_a" do
             it "renders the text in a bracket and includes a link in parens" do
               expect(subject.md_a("text", "link.md")).to eq "[text](link.md)"
             end
           end
 
-
           describe "#md_inline_type" do
             it "renders the code between single backticks" do
               expect(subject.md_inline_type("string")).to eq " (`String`)"

data/spec/brainstem/api_docs/formatters/markdown/presenter_formatter_spec.rb

@@ -68,7 +68,6 @@ module Brainstem
               end
             end
 
-
             describe "#format_brainstem_keys!" do
               before do
                 stub(presenter).brainstem_keys { [ "sprockets", "widgets" ] }
@@ -80,7 +79,6 @@ module Brainstem
               end
             end
 
-
             describe "#format_description!" do
               context "when present" do
                 before do
@@ -107,7 +105,6 @@ module Brainstem
               end
             end
 
-
             describe "#format_fields!" do
               let(:presenter_class) do
                 Class.new(Brainstem::Presenter) do
@@ -315,7 +312,6 @@ module Brainstem
                     end
                   end
 
-
                   context "if it is conditional" do
                     before do
                       presenter_class.fields do
@@ -383,7 +379,6 @@ module Brainstem
               end
             end
 
-
             describe "#format_filters!" do
               let(:valid_filters) { {} }
 
@@ -440,7 +435,6 @@ module Brainstem
               end
             end
 
-
             describe "format_sort_orders!" do
               before do
                 stub(presenter).valid_sort_orders { sort_orders }
@@ -492,7 +486,6 @@ module Brainstem
               end
             end
 
-
             describe "format_associations!" do
               let(:associations) { {} }
               let(:link) { nil }

data/spec/brainstem/api_docs/formatters/open_api_specification/helper_spec.rb

@@ -0,0 +1,210 @@
+require 'spec_helper'
+require 'brainstem/api_docs/formatters/open_api_specification/helper'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module OpenApiSpecification
+        describe Helper do
+          let(:klass) { Class.new { include Helper } }
+
+          subject { klass.new }
+
+          describe "presenter_title" do
+            let(:presenter)    { Presenter }
+            let(:target_class) { "cool_stuff" }
+
+            before do
+              mock(presenter).contextual_documentation(:title) { title }
+              stub(presenter).target_class { target_class }
+            end
+
+            context "when presenter has a title" do
+              let(:title) { "Awesome Sauce!" }
+
+              it "returns the title" do
+                expect(subject.presenter_title(presenter)).to eq(title)
+              end
+            end
+
+            context "when presenter does not have a title" do
+              let(:title) { nil }
+
+              it "returns the formatted target class of the presenter" do
+                expect(subject.presenter_title(presenter)).to eq("Cool Stuff")
+              end
+            end
+          end
+
+          describe "format_tag_name" do
+            context "when name is given" do
+              let(:title) { "awesome_sauce" }
+
+              it "returns the formatted name" do
+                expect(subject.format_tag_name(title)).to eq("Awesome Sauce")
+              end
+            end
+
+            context "when name is nil" do
+              let(:title) { nil }
+
+              it "returns nil" do
+                expect(subject.format_tag_name(title)).to be_nil
+              end
+            end
+          end
+
+          describe "format_description" do
+            context "when description is given" do
+              let(:description) { "  lorem ipsum dolor sit amet  " }
+
+              it "returns the formatted description" do
+                expect(subject.format_description(description)).to eq("Lorem ipsum dolor sit amet.")
+              end
+            end
+
+            context "when description is nil" do
+              let(:description) { "" }
+
+              it "returns nil" do
+                expect(subject.format_description(description)).to eq('')
+              end
+            end
+          end
+
+          describe "uncapitalize" do
+            context "when description is given" do
+              let(:description) { "  Lorem ipsum dolor sit amet  " }
+
+              it "returns the formatted description" do
+                expect(subject.uncapitalize(description)).to eq("lorem ipsum dolor sit amet")
+              end
+            end
+
+            context "when description is nil" do
+              let(:description) { "" }
+
+              it "returns nil" do
+                expect(subject.uncapitalize(description)).to eq("")
+              end
+            end
+          end
+
+          describe "format_http_method" do
+            let(:endpoint) { OpenStruct.new(http_methods: %w(PATCH PUT)) }
+
+            it "returns the first downcased http method" do
+              expect(subject.format_http_method(endpoint)).to eq("patch")
+            end
+          end
+
+          describe "type_and_format" do
+            context "when type is 'string'" do
+              it "returns the correct type and format" do
+                expect(subject.type_and_format('string')).to eq({ 'type' => 'string' })
+              end
+            end
+
+            context "when type is 'boolean'" do
+              it "returns the correct type and format" do
+                expect(subject.send(:type_and_format, 'boolean')).to eq({ 'type' => 'boolean' })
+              end
+            end
+
+            context "when type is 'integer'" do
+              it "returns the correct type and format" do
+                expect(subject.send(:type_and_format, 'integer')).to eq({ 'type' => 'integer', 'format' => 'int32' })
+              end
+            end
+
+            context "when type is 'long'" do
+              it "returns the correct type and format" do
+                expect(subject.send(:type_and_format, 'long')).to eq({ 'type' => 'integer', 'format' => 'int64' })
+              end
+            end
+
+            context "when type is 'float'" do
+              it "returns the correct type and format" do
+                expect(subject.send(:type_and_format, 'float')).to eq({ 'type' => 'number', 'format' => 'float' })
+              end
+            end
+
+            context "when type is 'double'" do
+              it "returns the correct type and format" do
+                expect(subject.send(:type_and_format, 'double')).to eq({ 'type' => 'number', 'format' => 'double' })
+              end
+            end
+
+            context "when type is 'byte'" do
+              it "returns the correct type and format" do
+                expect(subject.send(:type_and_format, 'byte')).to eq({ 'type' => 'string', 'format' => 'byte' })
+              end
+            end
+
+            context "when type is 'binary'" do
+              it "returns the correct type and format" do
+                expect(subject.send(:type_and_format, 'binary')).to eq({ 'type' => 'string', 'format' => 'binary' })
+              end
+            end
+
+            context "when type is 'date'" do
+              it "returns the correct type and format" do
+                expect(subject.send(:type_and_format, 'date')).to eq({ 'type' => 'string', 'format' => 'date' })
+              end
+            end
+
+            context "when type is 'datetime'" do
+              it "returns the correct type and format" do
+                expect(subject.send(:type_and_format, 'datetime')).to eq({ 'type' => 'string', 'format' => 'date-time' })
+              end
+            end
+
+            context "when type is 'password'" do
+              it "returns the correct type and format" do
+                expect(subject.send(:type_and_format, 'password')).to eq({ 'type' => 'string', 'format' => 'password' })
+              end
+            end
+
+            context "when type is 'id'" do
+              it "returns the correct type and format" do
+                expect(subject.send(:type_and_format, 'id')).to eq({ 'type' => 'integer', 'format' => 'int32' })
+              end
+            end
+
+            context "when type is 'decimal'" do
+              it "returns the correct type and format" do
+                expect(subject.send(:type_and_format, 'decimal')).to eq({ 'type' => 'number', 'format' => 'float' })
+              end
+            end
+
+            context "when type is array" do
+              context "when item type is not specified" do
+                it "returns type as `array` and item type as `string`" do
+                  expect(subject.send(:type_and_format, 'array')).to eq({
+                    'type' => 'array',
+                    'items' => { 'type' => 'string' }
+                  })
+                end
+              end
+
+              context "when item type is specified" do
+                it "returns type as `array` and given item type" do
+                  expect(subject.send(:type_and_format, 'array', 'integer')).to eq({
+                    'type' => 'array',
+                    'items' => { 'type' => 'integer' }
+                  })
+                end
+              end
+            end
+
+            context "when type is unknown" do
+              it "returns nil" do
+                expect(subject.send(:type_and_format, 'invalid')).to be_nil
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end