brainstem 1.1.1 → 1.3.0

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

@@ -129,19 +129,40 @@ module Brainstem
 
 
             describe "#format_params!" do
+              let(:const) do
+                Class.new do
+                  def self.brainstem_model_name
+                    :widget
+                  end
+                end
+              end
+
               before do
+                stub(controller).const { const }
+
                 subject.send(:format_params!)
               end
 
-
               context "with valid params" do
-                let(:show_config) { {
-                  valid_params: {
-                    only: { info: "which ids to include", nodoc: nodoc },
-                    sprocket_id: { info: "the id of the sprocket", root: "widget", nodoc: nodoc },
-                    sprocket_child: { recursive: true, legacy: false, info: "it does the thing", root: "widget" },
+                let(:root_proc) { Proc.new { "widget" } }
+                let(:sprocket_id_proc) { Proc.new { "sprocket_id" } }
+                let(:sprocket_child_proc) { Proc.new { "sprocket_child" } }
+                let(:default_show_config) {
+                  {
+                    valid_params: {
+                      only: {
+                        info: "which ids to include", nodoc: nodoc, type: "array", item_type: "integer"
+                      },
+                      sprocket_id_proc => {
+                        info: "the id of the sprocket", root: root_proc, ancestors: [root_proc], nodoc: nodoc, type: "integer"
+                      },
+                      sprocket_child_proc => {
+                        recursive: true, legacy: false, info: "it does the thing", root: root_proc, ancestors: [root_proc], type: "string"
+                      },
+                    }
                   }
-                } }
+                }
+                let(:show_config) { default_show_config }
 
                 context "when nodoc" do
                   let(:nodoc) { true }
@@ -169,12 +190,18 @@ module Brainstem
 
                   context "for non-root params" do
                     it "outputs sub params under a list item" do
-                      expect(subject.output).to include "- `widget`\n    - `sprocket_id` - the id of the sprocket\n    - `sprocket_child`"
+                      expect(subject.output).to include "- `widget` (`Hash`)\n    - `sprocket_id` (`Integer`) - the id of the sprocket\n    - `sprocket_child` (`String`)"
+                    end
+                  end
+
+                  context "for params with type array" do
+                    it "outputs item type along with the field type" do
+                      expect(subject.output).to include "- `only` (`Array<Integer>`) - which ids to include\n"
                     end
                   end
 
                   it "includes the info on a hash key" do
-                    expect(subject.output).to include "`sprocket_child` - it does the thing"
+                    expect(subject.output).to include "`sprocket_child` (`String`) - it does the thing"
                   end
 
                   it "includes the recursivity if specified" do
@@ -184,14 +211,82 @@ module Brainstem
                   it "includes the legacy status if specified" do
                     expect(subject.output).to include "Legacy: false"
                   end
+
+                  context "when required option is specified" do
+                    let(:show_config) {
+                      default_show_config.tap do |config|
+                        config[:valid_params][sprocket_id_proc][:required] = required
+                      end
+                    }
+
+                    context "when required is true" do
+                      let(:required) { true }
+
+                      it "includes if required" do
+                        expect(subject.output).to include "Required: true"
+                      end
+                    end
+
+                    context "when required is false" do
+                      let(:required) { false }
+
+                      it "includes if required" do
+                        expect(subject.output).to_not include "Required"
+                      end
+                    end
+                  end
+
+                  context "with multiple levels of nested params" do
+                    let(:sprocket_template_proc) { Proc.new { "sprocket_template" } }
+                    let(:sprocket_template_json_proc) { Proc.new { "sprocket_template_json" } }
+                    let(:sprocket_template_title_proc) { Proc.new { "sprocket_template_title" } }
+                    let(:multi_nested_params) {
+                      {
+                        sprocket_template_proc => {
+                          info: "the template for the sprocket",
+                          type: "hash",
+                          root: root_proc,
+                          ancestors: [root_proc]
+                        },
+                        sprocket_template_json_proc => {
+                          info: "the json blob of the sprocket template",
+                          type: "string",
+                          ancestors: [root_proc, sprocket_template_proc]
+                        },
+                        sprocket_template_title_proc => {
+                          info: "the title of the sprocket template",
+                          type: "string",
+                          ancestors: [root_proc, sprocket_template_proc]
+                        }
+                      }
+                    }
+                    let(:show_config) {
+                      default_show_config.tap do |config|
+                        config[:valid_params].merge!(multi_nested_params)
+                      end
+                    }
+
+                    it "outputs sub params under a list item" do
+                      output = subject.output
+                      expect(output).to include("##### Valid Parameters\n\n")
+                      expect(output).to include("- `only` (`Array<Integer>`) - which ids to include\n")
+                      expect(output).to include("- `widget` (`Hash`)\n")
+                      expect(output).to include("    - `sprocket_id` (`Integer`) - the id of the sprocket\n")
+                      expect(output).to include("    - `sprocket_child` (`String`) - it does the thing\n")
+                      expect(output).to include("        - Legacy: false\n")
+                      expect(output).to include("        - Recursive: true\n")
+                      expect(output).to include("    - `sprocket_template` (`Hash`) - the template for the sprocket\n")
+                      expect(output).to include("        - `sprocket_template_json` (`String`) - the json blob of the sprocket template\n")
+                      expect(output).to include("        - `sprocket_template_title` (`String`) - the title of the sprocket template\n\n\n")
+                    end
+                  end
                 end
               end
 
-
               context "with only default params" do
                 let(:default_config) { {
                   valid_params: {
-                    sprocket_name: {
+                    Proc.new { "sprocket_name" } => {
                       info: "the name of the sprocket",
                       nodoc: nodoc
                     }
@@ -218,10 +313,8 @@ module Brainstem
                   expect(subject.output).to eq ""
                 end
               end
-
             end
 
-
             describe "#format_presents!" do
               let(:presenter) { Object.new }
 

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

@@ -93,6 +93,25 @@ module Brainstem
               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`)"
+            end
+
+            context "when type is blank" do
+              it "returns an empty string" do
+                expect(subject.md_inline_type("")).to eq ""
+              end
+            end
+
+            context "when item type is specified" do
+              it "renders the code between single backticks" do
+                expect(subject.md_inline_type("array", "integer")).to eq " (`Array<Integer>`)"
+              end
+            end
+          end
         end
       end
     end

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

@@ -54,7 +54,6 @@ module Brainstem
             end
           end
 
-
           describe "formatting" do
             let(:lorem) { "lorem ipsum dolor sit amet" }
 
@@ -110,39 +109,39 @@ module Brainstem
 
 
             describe "#format_fields!" do
-              let(:valid_fields) { {} }
+              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) { {} }
-              let(:optional)     { false }
-
-              let(:sprocket_name_long) { OpenStruct.new(
-                name:        :sprocket_name,
-                description: lorem,
-                options:     { via: :name },
-                type:        :string
-              ) }
-
-              let(:sprocket_name_short) { OpenStruct.new(
-                name:    :sprocket_name,
-                type:    :string,
-                options: { }
-              ) }
 
               before do
-                stub(sprocket_name_long).optional?  { optional }
-                stub(sprocket_name_short).optional? { optional }
-                stub(presenter).conditionals        { conditionals }
-                stub(presenter).valid_fields        { valid_fields }
-                subject.send(:format_fields!)
+                stub(presenter).conditionals { conditionals }
               end
 
               it "outputs a header" do
+                presenter_class.fields do
+                  field :name, :string
+                end
+                subject.send(:format_fields!)
+
                 expect(subject.output).to include "Fields"
               end
 
               context "with fields present" do
                 context "branch node" do
                   context "with single branch" do
-                    let(:valid_fields) { { sprockets: { name: sprocket_name_long } } }
+                    before do
+                      presenter_class.fields do
+                        fields :sprockets do
+                          field :sprocket_name, :string, via: :name, info: "whatever"
+                        end
+                      end
+
+                      subject.send(:format_fields!)
+                    end
 
                     it "outputs the name of the branch as a list item" do
                       expect(subject.output.scan(/\n-/).count).to eq 1
@@ -151,13 +150,22 @@ module Brainstem
                     end
 
                     it "outputs the child nodes as sub-list items" do
-                      expect(subject.output).to \
-                        include("\n- `sprockets`\n    - `sprocket_name`")
+                      expect(subject.output).to include("\n- `sprockets` (`Hash`)\n    - `sprocket_name`")
                     end
                   end
 
                   context "with sub-branch" do
-                    let(:valid_fields) { { sprockets: { sub_sprocket: { name: sprocket_name_long } } } }
+                    before do
+                      presenter_class.fields do
+                        fields :sprockets do
+                          fields :sub_sprocket do
+                            field :sprocket_name, :string, via: :name, info: "whatever"
+                          end
+                        end
+                      end
+
+                      subject.send(:format_fields!)
+                    end
 
                     it "outputs the name of sub-branches as a sub-list item" do
                       expect(subject.output.scan(/\n-/).count).to eq 1
@@ -168,13 +176,60 @@ module Brainstem
 
                     it "outputs the child nodes as sub-list items" do
                       expect(subject.output).to \
-                        include("\n- `sprockets`\n    - `sub_sprocket`\n        - `sprocket_name`")
+                        include("\n- `sprockets` (`Hash`)\n    - `sub_sprocket` (`Hash`)\n        - `sprocket_name`")
+                    end
+                  end
+
+                  context "when branch has properties" do
+                    let(:conditionals) do
+                      {
+                        :it_is_a_friday => OpenStruct.new(
+                          description: "it is a friday",
+                          name: :it_is_a_friday,
+                          type: :request,
+                          options: {}
+                        )
+                      }
+                    end
+
+                    before do
+                      presenter_class.fields do
+                        fields :sprockets, :array, info: "parent", if: :it_is_a_friday do
+                          field :sprocket_name, :string, via: :name, info: "whatever"
+                        end
+                      end
+
+                      subject.send(:format_fields!)
+                    end
+
+                    it "outputs the name of the branch as a list item" do
+                      expect(subject.output.scan(/\n-/).count).to eq 1
+                      expect(subject.output.scan(/\n    -/).count).to eq 3
+                      expect(subject.output.scan(/\n        -/).count).to eq 2
+                    end
+
+                    it "outputs the parent node with its properties" do
+                      result = subject.output
+
+                      expect(result).to include("##### Fields\n\n")
+                      expect(result).to include("- `sprockets` (`Array`)\n")
+                      expect(result).to include("    - parent\n")
+                      expect(result).to include("    - visible when it is a friday\n")
+                      expect(result).to include("    - `sprocket_name` (`String`)\n")
+                      expect(result).to include("        - whatever\n")
+                      expect(result).to include("        - visible when it is a friday\n\n\n\n")
                     end
                   end
                 end
 
                 context "leaf node" do
-                  let(:valid_fields) { { sprocket_name: sprocket_name_long } }
+                  before do
+                    presenter_class.fields do
+                      field :sprocket_name, :string, via: :name
+                    end
+
+                    subject.send(:format_fields!)
+                  end
 
                   context "if it is not conditional" do
                     it "outputs each field as a list item" do
@@ -191,7 +246,16 @@ module Brainstem
 
                     describe "optional" do
                       context "when true" do
-                        let(:optional) { true }
+                        before do
+                          presenter_class.fields do
+                            field :sprocket_name, :string,
+                              info: "lorem ipsum dolor sit amet",
+                              optional: true,
+                              via: :name
+                          end
+
+                          subject.send(:format_fields!)
+                        end
 
                         it "says so" do
                           expect(subject.output).to include "only returned when requested"
@@ -208,29 +272,58 @@ module Brainstem
 
                     describe "description" do
                       context "when present" do
+                        before do
+                          presenter_class.fields do
+                            field :sprocket_name, :string, info: "lorem ipsum dolor sit amet"
+                          end
+
+                          subject.send(:format_fields!)
+                        end
+
                         it "outputs the description" do
                           expect(subject.output).to include "    - #{lorem}"
                         end
                       end
 
                       context "when absent" do
-                        let(:valid_fields) { { sprocket_name: sprocket_name_short } }
+                        before do
+                          presenter_class.fields do
+                            field :sprocket_name, :string
+                          end
+
+                          subject.send(:format_fields!)
+                        end
 
                         it "does not include the description" do
                           expect(subject.output).not_to include "    -"
                         end
                       end
                     end
+
+                    describe "when field has an item type" do
+                      before do
+                        presenter_class.fields do
+                          field :sprocket_ids, :array, item_type: :integer
+                        end
+
+                        subject.send(:format_fields!)
+                      end
+
+                      it "outputs each field's type along with the sub item type" do
+                        expect(subject.output).to include "`sprocket_ids` (`Array<Integer>`)"
+                      end
+                    end
                   end
 
 
                   context "if it is conditional" do
-                    let(:sprocket_name_long) { OpenStruct.new(
-                      name: :sprocket_name,
-                      description: lorem,
-                      options: { via: :name, if: [:it_is_a_friday] },
-                      type: :string
-                    ) }
+                    before do
+                      presenter_class.fields do
+                        field :sprocket_name, :string, if: :it_is_a_friday
+                      end
+
+                      subject.send(:format_fields!)
+                    end
 
                     context "if nodoc" do
                       let(:conditionals) { {
@@ -303,8 +396,9 @@ module Brainstem
                 let(:valid_filters) {
                   {
                     "published" => {
+                      type:  "string",
                       value: Proc.new { nil },
-                      info: "limits to published"
+                      info:  "limits to published"
                     }
                   }
                 }
@@ -315,9 +409,28 @@ module Brainstem
 
                 it "lists them" do
                   expect(subject.output.scan(/\n-/).count).to eq 1
-                  expect(subject.output).to include "`published`"
+                  expect(subject.output).to include "`published` (`String`)"
                   expect(subject.output).to include "    - limits to published"
                 end
+
+                context "when items specified" do
+                  let(:valid_filters) {
+                    {
+                      "published" => {
+                        type:  "string",
+                        value: Proc.new { nil },
+                        info:  "limits to published",
+                        items: ["fizz", "buzz"]
+                      }
+                    }
+                  }
+
+                  it "lists them with items" do
+                    expect(subject.output.scan(/\n-/).count).to eq 1
+                    expect(subject.output).to include "`published` (`String`)"
+                    expect(subject.output).to include "    - limits to published. Available values: fizz, buzz."
+                  end
+                end
               end
 
               context "when no filters" do