paradocs 1.0.22 → 1.1.2

data/lib/paradocs/whitelist.rb

@@ -32,12 +32,14 @@ module Paradocs
 
       def resolve(payload, schema, context)
         filtered_payload = {}
+        coercion_block = Paradocs.config.whitelist_coercion
+        coercion_block = coercion_block.is_a?(Proc) && coercion_block
         payload.dup.each do |key, value|
           key    = key.to_sym
           schema = Schema.new if schema.nil?
           schema.send(:flush!)
           schema.send(:invoke_subschemes!, payload, context)
-
+          meta = get_meta_data(schema, key)
           if value.is_a?(Hash)
             field_schema = find_schema_by(schema, key)
             value        = resolve(value, field_schema, context)
@@ -47,13 +49,14 @@ module Paradocs
                 field_schema = find_schema_by(schema, key)
                 resolve(v, field_schema, context)
               else
-                v = FILTERED unless whitelisted?(schema, key)
+                v = FILTERED unless whitelisted?(meta, key)
                 v
               end
             end
           else
-            value = if whitelisted?(schema, key)
-              value
+
+            value = if whitelisted?(meta, key)
+              coercion_block ? coercion_block.call(value, meta) : value
             elsif value.nil? || value.try(:blank?) || value.try(:empty?)
               !!value == value ? value : EMPTY
             else
@@ -61,7 +64,6 @@ module Paradocs
             end
             value
           end
-
           filtered_payload[key] = value
         end
 
@@ -71,13 +73,12 @@ module Paradocs
       private
 
       def find_schema_by(schema, key)
-        meta_data = get_meta_data(schema, key)
-        meta_data[:schema]
+        meta = get_meta_data(schema, key)
+        meta[:schema]
       end
 
-      def whitelisted?(schema, key)
-        meta_data = get_meta_data(schema, key)
-        meta_data[:whitelisted] || Paradocs.config.whitelisted_keys.include?(key)
+      def whitelisted?(meta, key)
+        meta[:whitelisted] || Paradocs.config.whitelisted_keys.include?(key)
       end
 
       def get_meta_data(schema, key)

data/mkdocs.yml

@@ -0,0 +1,17 @@
+site_name: Paradocs
+theme:
+    name: readthedocs
+    nav_style: dark
+nav:
+  - 'index.md'
+  - 'policies.md'
+  - 'schema.md'
+  - 'struct.md'
+  - 'form_objects_dsl.md'
+  - 'subschema.md'
+  - 'documentation_generation.md'
+  - 'payload_builder.md'
+  - 'custom_configuration.md'
+  - 'faq.md'
+  - 'changelog.md'
+

data/paradocs.gemspec

@@ -6,11 +6,11 @@ require 'paradocs/version'
 Gem::Specification.new do |spec|
   spec.name          = "paradocs"
   spec.version       = Paradocs::VERSION
-  spec.authors       = ["Ismael Celis", "Maxim Tkachenko"]
-  spec.email         = ["ismaelct@gmail.com", "tkachenko.maxim.w@gmail.com"]
+  spec.authors       = ["Maxim Tkachenko", "Ismael Celis"]
+  spec.email         = ["tkachenko.maxim.w@gmail.com", "ismaelct@gmail.com"]
   spec.description   = %q{Flexible DSL for declaring allowed parameters focused on DRY validation that gives you opportunity to generate API documentation on-the-fly.}
   spec.summary       = %q{A huge add-on for original gem mostly focused on retrieving the more metadata from declared schemas as possible.}
-  spec.homepage      = "https://github.com/mtkachenk0/paradocs"
+  spec.homepage      = "https://paradocs.readthedocs.io/en/latest"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")
@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 2.1"
-  spec.add_development_dependency "rake", "~> 0"
+  spec.add_development_dependency "rake", '~> 12.3'
   spec.add_development_dependency "rspec", '3.4.0'
   spec.add_development_dependency "pry", "~> 0"
 end

data/requirements.txt

@@ -0,0 +1 @@
+mkdocs==1.1.2

data/spec/extensions/payload_builder_spec.rb

@@ -0,0 +1,70 @@
+require "spec_helper"
+
+describe Paradocs::Extensions::PayloadBuilder do
+  let(:schema) do
+    Paradocs::Schema.new do
+      field(:test).present.type(:string).mutates_schema! { :subschema1 }
+      subschema(:subschema1) do
+        field(:subtest1).declared.type(:number)
+      end
+      subschema(:subschema2) do
+        field(:subtest2).required.type(:array).schema do
+          field(:hello).type(:string).mutates_schema! { |*| :deep_schema }
+          subschema(:deep_schema) { field(:deep_field).type(:boolean) }
+          subschema(:empty) { }
+        end
+      end
+      # 2 mutation fields and more than 1 subschema pack work good in validation but docs
+      # will contain only 1 subschema at once: foo subschemes will never be mixed with test subschemes
+      field(:foo).required.type(:object).schema do
+        field(:bar).present.type(:string).options(["foo", "bar"]).mutates_schema! do |value, *|
+          value == "foo" ? :fooschema : :barschema
+        end
+        subschema(:fooschema) { }
+        subschema(:barschema) do
+          field(:barfield).present.type(:boolean)
+        end
+      end
+    end
+  end
+
+  it "gives an example payload and takes into account the subschemes" do
+    allow_any_instance_of(Array).to receive(:sample) { "bar" }
+    payloads = described_class.new(schema).build!
+    expect(payloads.keys.sort).to eq([:barschema, :fooschema, :subschema1, :subschema2_deep_schema, :subschema2_empty])
+    expect(payloads[:barschema]).to eq({"test" => nil, "foo" => {"bar" => "bar", "barfield" => nil}})
+    expect(payloads[:fooschema]).to eq({"test" => nil, "foo" => {"bar" => "bar"}})
+    expect(payloads[:subschema1]).to eq({"test" => nil, "foo"  => {"bar" => "bar"}, "subtest1" => nil})
+    expect(payloads[:subschema2_deep_schema]).to eq({
+      "subtest2" => [{"deep_field" => nil, "hello" => nil}], "test" => nil, "foo" => {"bar" => "bar"}
+    })
+    expect(payloads[:subschema2_empty]).to eq({
+      "test" => nil, "foo" => {"bar" => "bar"}, "subtest2" => [{"hello" => nil}]
+    })
+  end
+
+  it "yields a usefull block that changes the result" do
+    payloads = described_class.new(schema).build! do |key, meta, example, skip_word|
+      if key == "bar"
+        nil
+      elsif meta[:type] == :boolean
+        true
+      elsif key == "subtest1"
+        skip_word # this key value pair will be ommited
+      else
+        example # return suggested value
+      end
+    end
+
+    expect(payloads.keys.sort).to eq([:barschema, :fooschema, :subschema1, :subschema2_deep_schema, :subschema2_empty])
+    expect(payloads[:barschema]).to eq({"test" => nil, "foo" => {"bar" => nil, "barfield" => true}}) # barfield is change to true and bar is nil
+    expect(payloads[:fooschema]).to eq({"test" => nil, "foo" => {"bar" => nil}}) # bar is nil
+    expect(payloads[:subschema1]).to eq({"test" => nil, "foo"  => {"bar" => nil}}) # subtest is missing, bar is nil
+    expect(payloads[:subschema2_deep_schema]).to eq({
+      "subtest2" => [{"deep_field" => true, "hello" => nil}], "test" => nil, "foo" => {"bar" => nil}
+    })
+    expect(payloads[:subschema2_empty]).to eq({
+      "test" => nil, "foo" => {"bar" => nil}, "subtest2" => [{"hello" => nil}]
+    })
+  end
+end

data/spec/extensions/structures_spec.rb

@@ -0,0 +1,244 @@
+require 'spec_helper'
+
+describe Paradocs::Extensions::Structure do
+  Paradocs.policy :policy_with_error do
+    register_error ArgumentError
+
+    validate do |*|
+      raise ArgumentError
+    end
+  end
+
+  Paradocs.policy :policy_with_silent_error do
+    register_silent_error RuntimeError
+  end
+
+  let(:schema) do
+    Paradocs::Schema.new do
+      subschema(:highest_level) { field(:test).present } # no mutations on this level -> subschema ignored
+
+      field(:data).type(:object).present.schema do
+        field(:id).type(:integer).present.policy(:policy_with_error)
+        field(:name).type(:string).meta(label: "very important staff")
+        field(:role).type(:string).declared.options(["admin", "user"]).default("user").mutates_schema! do |*|
+          :test_subschema
+        end
+        field(:extra).type(:array).required.schema do
+          field(:extra).declared.default(false).policy(:policy_with_silent_error)
+        end
+
+        mutation_by!(:name) { :subschema }
+
+        subschema(:subschema) do
+          field(:test_field).present
+        end
+        subschema(:test_subschema) do
+          field(:test1).present
+        end
+      end
+    end
+  end
+
+  describe "#nested" do
+    it "generates nested data for documentation generation" do
+      result = schema.structure.nested { |k, meta| meta[:block_works] = true unless meta[:present] }
+      expect(result[:_subschemes]).to eq({})
+      expect(result[:_errors]).to eq([ArgumentError])
+      data_structure = result[:data].delete(:structure)
+      expect(result[:data]).to eq({
+        type: :object,
+        required: true,
+        present: true,
+        json_path: "$.data",
+        nested_name: "data",
+      })
+      expect(data_structure[:_subschemes]).to eq({
+        test_subschema: {
+          _errors: [],
+          _subschemes: {},
+          test1: {required: true, present: true, json_path: "$.data.test1", nested_name: "data.test1"}
+        },
+        subschema: {
+          _errors: [],
+          _subschemes: {},
+          test_field: {required: true, present: true, json_path: "$.data.test_field", nested_name: "data.test_field"}
+        }
+      })
+      expect(data_structure[:id]).to eq({
+        type: :integer,
+        required: true,
+        present: true,
+        policy_with_error: {errors: [ArgumentError]},
+        json_path: "$.data.id",
+        nested_name: "data.id"
+      })
+      expect(data_structure[:name]).to eq({
+        type: :string,
+        label: "very important staff",
+        mutates_schema: true,
+        block_works: true,
+        json_path: "$.data.name",
+        nested_name: "data.name"
+      })
+      expect(data_structure[:role]).to eq({
+        type: :string,
+        options: ["admin", "user"],
+        default: "user",
+        mutates_schema: true,
+        block_works: true,
+        json_path: "$.data.role",
+        nested_name: "data.role"
+      })
+      expect(data_structure[:extra]).to eq({
+        type: :array,
+        required: true,
+        block_works: true,
+        json_path: "$.data.extra[]",
+        nested_name: "data.extra",
+        structure: {
+          extra: {
+            default: false,
+            block_works: true,
+            json_path: "$.data.extra[].extra",
+            nested_name: "data.extra.extra",
+            policy_with_silent_error: {errors: []}
+          },
+          _subschemes: {}
+        }
+      })
+    end
+  end
+
+  describe "#flatten" do
+    it "generates flatten data for documentation generation" do
+      expect(schema.structure.flatten { |key, meta| meta[:block_works] = true if key.split(".").size == 1 }).to eq({
+        "data" => {
+          type: :object,
+          required: true,
+          present: true,
+          block_works: true,
+          json_path: "$.data"
+        },
+        "data.extra" => {
+          type: :array,
+          required: true,
+          json_path: "$.data.extra[]"
+        },
+        "data.extra.extra" => {
+          default: false,
+          json_path: "$.data.extra[].extra",
+          policy_with_silent_error: {errors: []}
+        },
+        "data.id" => {
+          type: :integer,
+          required: true,
+          present: true,
+          json_path: "$.data.id",
+          policy_with_error: {errors: [ArgumentError]}
+        },
+        "data.name" => {
+          type: :string,
+          json_path: "$.data.name",
+          label: "very important staff",
+          mutates_schema: true
+        },
+        "data.role" => {
+          type: :string,
+          options: ["admin", "user"],
+          default: "user",
+          json_path: "$.data.role",
+          mutates_schema: true
+        },
+        _errors: [ArgumentError],
+        _subschemes: {
+          test_subschema: {
+            _errors: [],
+            _subschemes: {},
+            "data.test1"=>{
+              required: true,
+              present: true,
+              json_path: "$.data.test1"
+            }
+          },
+          subschema: {
+            _errors: [],
+            _subschemes: {},
+            "data.test_field" => {required: true, present: true, json_path: "$.data.test_field"}
+          }
+        }
+      })
+    end
+  end
+
+  describe "#all_flatten" do
+    it "generates N structures, where N = number of unique combinations of applied subschemas" do
+      expect(schema.structure.all_flatten).to eq({
+        subschema: {
+          _errors: [ArgumentError],
+          "data"             => {type: :object, required: true, present: true, json_path: "$.data"},
+          "data.id"          => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id"},
+          "data.name"        => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true},
+          "data.role"        => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true},
+          "data.extra"       => {type: :array, required: true, json_path: "$.data.extra[]"},
+          "data.extra.extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra"},
+          "data.test_field"  => {required: true, present: true, json_path: "$.data.test_field"}
+        },
+        test_subschema: {
+          _errors: [ArgumentError],
+          "data"             => {type: :object, required: true, present: true, json_path: "$.data"},
+          "data.id"          => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id"},
+          "data.name"        => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true},
+          "data.role"        => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true},
+          "data.extra"       => {type: :array, required: true, json_path: "$.data.extra[]"},
+          "data.extra.extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra"},
+          "data.test1"       => {required: true, present: true, json_path: "$.data.test1"}
+        }
+      })
+    end
+  end
+
+  describe "#all_nested" do
+    it "generates N structures, where N = number of unique combinations of applied subschemas" do
+      result = schema.structure.all_nested
+      expect(result[:subschema]).to eq({
+        _errors:     [ArgumentError],
+        "data" => {
+          type:        :object,
+          required:    true,
+          present:     true,
+          json_path:   "$.data",
+          nested_name: "data",
+          structure: {
+            "role"       => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", nested_name: "data.role", mutates_schema: true},
+            "test_field" => {required: true, present: true, json_path: "$.data.test_field", nested_name: "data.test_field"},
+            "id"         => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id", nested_name: "data.id"},
+            "name"       => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true, nested_name: "data.name"},
+            "extra"      => {
+              type: :array, required: true, json_path: "$.data.extra[]", nested_name: "data.extra",
+              structure: {"extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra", nested_name: "data.extra.extra"}}
+            }
+          }
+        }
+      })
+      expect(result[:test_subschema]).to eq({
+        _errors:     [ArgumentError],
+        "data" => {
+          type:      :object,
+          required:  true,
+          present:   true,
+          json_path: "$.data",
+          nested_name: "data",
+          structure: {
+            "role"  => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", nested_name: "data.role", mutates_schema: true},
+            "test1" => {required: true, present: true, json_path: "$.data.test1", nested_name: "data.test1"},
+            "id"    => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id", nested_name: "data.id"},
+            "name"  => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true, nested_name: "data.name"},
+            "extra" => {
+              type: :array, required: true, json_path: "$.data.extra[]", nested_name: "data.extra",
+              structure: {"extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra", nested_name: "data.extra.extra"}}}
+          }
+        }
+      })
+    end
+  end
+end

data/spec/schema_spec.rb

@@ -32,7 +32,7 @@ describe Paradocs::Schema do
 
   describe "#structure" do
     it "represents data structure and meta data" do
-      sc = subject.structure
+      sc = subject.structure.nested
       expect(sc[:title][:present]).to be true
       expect(sc[:title][:type]).to eq :string
       expect(sc[:price][:type]).to eq :integer

data/spec/struct_spec.rb

@@ -2,7 +2,7 @@ require 'spec_helper'
 require 'paradocs/struct'
 
 describe Paradocs::Struct do
-  it "works" do
+  it 'works' do
     friend_class = Class.new do
       include Paradocs::Struct
 
@@ -53,7 +53,7 @@ describe Paradocs::Struct do
     expect(invalid_instance.friends[1].errors['$.name']).not_to be_nil
   end
 
-  it "is inmutable by default" do
+  it 'is inmutable by default' do
     klass = Class.new do
       include Paradocs::Struct
 
@@ -66,7 +66,7 @@ describe Paradocs::Struct do
 
     instance = klass.new
     expect {
-      instance.title = "foo"
+      instance.title = 'foo'
     }.to raise_error NoMethodError
 
     expect {
@@ -74,7 +74,7 @@ describe Paradocs::Struct do
     }.to raise_error RuntimeError
   end
 
-  it "works with anonymous nested schemas" do
+  it 'works with anonymous nested schemas' do
     klass = Class.new do
       include Paradocs::Struct
 
@@ -125,7 +125,7 @@ describe Paradocs::Struct do
     expect(user.friends.first.salutation).to eq 'my age is 43'
   end
 
-  it "wraps regular schemas in structs" do
+  it 'wraps regular schemas in structs' do
     friend_schema = Paradocs::Schema.new do
       field(:name)
     end
@@ -147,7 +147,7 @@ describe Paradocs::Struct do
     expect(instance.friends.first.name).to eq 'Ismael'
   end
 
-  it "#to_h" do
+  it '#to_h' do
     klass = Class.new do
       include Paradocs::Struct
 
@@ -185,7 +185,7 @@ describe Paradocs::Struct do
     expect(new_instance.to_h[:title]).to eq 'foo'
   end
 
-  it "works with inheritance" do
+  it 'works with inheritance' do
     klass = Class.new do
       include Paradocs::Struct
 
@@ -218,7 +218,7 @@ describe Paradocs::Struct do
     expect(instance.friends.size).to eq 2
   end
 
-  it "implements deep struct equality" do
+  it 'implements deep struct equality' do
     klass = Class.new do
       include Paradocs::Struct
 
@@ -268,7 +268,7 @@ describe Paradocs::Struct do
     expect(s1 == s4).to be false
   end
 
-  it "#merge returns a new instance" do
+  it '#merge returns a new instance' do
     klass = Class.new do
       include Paradocs::Struct
 
@@ -301,6 +301,20 @@ describe Paradocs::Struct do
     expect(copy.friends.first.name).to eq 'jane'
   end
 
+  it 'passes the environment to the schema' do
+    klass = Class.new do
+      include Paradocs::Struct
+
+      schema do
+        field(:age).type(:integer)
+      end
+    end
+
+    new_instance = klass.new({}, { key: :value })
+
+    expect(new_instance.send(:_results).environment).to eq({ key: :value })
+  end
+
   describe '.new!' do
     it 'raises a useful exception if invalid data' do
       klass = Class.new do
@@ -320,5 +334,19 @@ describe Paradocs::Struct do
       valid = klass.new!(title: 'foo')
       expect(valid.title).to eq 'foo'
     end
+
+    it 'passes the environment to the schema' do
+      klass = Class.new do
+        include Paradocs::Struct
+
+        schema do
+          field(:title).type(:string).present
+        end
+      end
+
+      new_instance = klass.new!({ title: 'test' }, { key: :value })
+
+      expect(new_instance.send(:_results).environment).to eq({ key: :value })
+    end
   end
 end