paradocs 1.0.23 → 1.1.3

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

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   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", ">= 12.3.3"
+  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,248 @@
+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").description("Example description").example("John")
+        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",
+        description: "Example description",
+        example: "John",
+        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",
+          description: "Example description",
+          example: "John",
+          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, description: "Example description", example: "John"},
+          "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, description: "Example description", example: "John"},
+          "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", description: "Example description", example: "John"},
+            "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", description: "Example description", example: "John"},
+            "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/field_spec.rb

@@ -1,7 +1,7 @@
 require "spec_helper"
 
 describe Paradocs::Field do
-  let(:context)  { Paradocs::Context.new }
+  let(:context) { Paradocs::Context.new }
 
   subject { described_class.new(:a_key) }
 

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/subschema_spec.rb

@@ -71,16 +71,16 @@ describe "schemes with subschemes" do
       result = schema.resolve({error: :here})
       expect(result.errors).to    eq({"$.fail_field"=>["is required"]})
       expect(result.output).to    eq({error: :here, fail_field: nil})
-      expect(schema.structure).to eq(structure)
-      expect(schema.structure(ignore_transparent: false)).to eq(structure.merge(
+      expect(schema.structure.nested).to eq(structure)
+      expect(schema.structure(ignore_transparent: false).nested).to eq(structure.merge(
         error: {transparent: true, mutates_schema: true, json_path: "$.error", nested_name: "error"}
       ))
 
       result = schema.resolve({})
       expect(result.errors).to eq({"$.success_field"=>["is required"]})
       expect(result.output).to eq({success_field: nil})
-      expect(schema.structure).to eq(structure)
-      expect(schema.structure(ignore_transparent: false)).to eq(structure.merge(
+      expect(schema.structure.nested).to eq(structure)
+      expect(schema.structure(ignore_transparent: false).nested).to eq(structure.merge(
         error: {transparent: true, mutates_schema: true, json_path: "$.error", nested_name: "error"}
       ))
     end

data/spec/whitelist_spec.rb

@@ -93,5 +93,38 @@ describe "classes including Whitelist module" do
         }
       )
     end
+
+    context "when Paradocs.config.whitelist_coercion block is set" do
+      before { Paradocs.config.whitelist_coercion = Proc.new { |value, meta| meta[:type] != :string ? "FILTER" : value.to_s }}
+
+      it "executes block for each value" do
+        whitelisted = TestWhitelist.new.filter!(input, schema)
+        expect(whitelisted).to eq(
+          {
+            unexpected: "[FILTERED]",
+            from_config: "FILTER",
+            data: [
+              {
+                id: "5",
+                name: "[EMPTY]",
+                unexpected: "[EMPTY]",
+                empty_array: [],
+                subschema_1: "FILTER",
+                subfield_1: "FILTER",
+                subschema_2: "[FILTERED]",
+                subfield_2: "FILTER",
+                empty_hash: {},
+                extra: {
+                  id: "6",
+                  name: "[FILTERED]",
+                  unexpected: "[FILTERED]",
+                  empty_string: "[EMPTY]"
+                }
+              }
+            ]
+          }
+        )
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paradocs
 version: !ruby/object:Gem::Version
-  version: 1.0.23
+  version: 1.1.3
 platform: ruby
 authors:
 - Maxim Tkachenko
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-09-01 00:00:00.000000000 Z
+date: 2020-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -29,16 +29,16 @@ dependencies:
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 12.3.3
+        version: '12.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 12.3.3
+        version: '12.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +80,7 @@ files:
 - ".github/workflows/spec.yml"
 - ".gitignore"
 - ".gitlab-ci.yml"
+- ".readthedocs.yml"
 - ".rspec"
 - ".travis.yml"
 - Gemfile
@@ -87,12 +88,24 @@ files:
 - README.md
 - Rakefile
 - bin/console
+- docs/changelog.md
+- docs/custom_configuration.md
+- docs/documentation_generation.md
+- docs/faq.md
+- docs/form_objects_dsl.md
+- docs/index.md
+- docs/payload_builder.md
+- docs/policies.md
+- docs/schema.md
+- docs/struct.md
+- docs/subschema.md
 - lib/paradocs.rb
 - lib/paradocs/base_policy.rb
 - lib/paradocs/context.rb
 - lib/paradocs/default_types.rb
 - lib/paradocs/dsl.rb
-- lib/paradocs/extensions/insides.rb
+- lib/paradocs/extensions/payload_builder.rb
+- lib/paradocs/extensions/structure.rb
 - lib/paradocs/field.rb
 - lib/paradocs/field_dsl.rb
 - lib/paradocs/policies.rb
@@ -103,23 +116,26 @@ files:
 - lib/paradocs/support.rb
 - lib/paradocs/version.rb
 - lib/paradocs/whitelist.rb
+- mkdocs.yml
 - paradocs.gemspec
+- requirements.txt
 - spec/custom_block_validator_spec.rb
 - spec/custom_validator.rb
 - spec/dsl_spec.rb
 - spec/expand_spec.rb
+- spec/extensions/payload_builder_spec.rb
+- spec/extensions/structures_spec.rb
 - spec/field_spec.rb
 - spec/helpers.rb
 - spec/policies_spec.rb
 - spec/schema_spec.rb
-- spec/schema_structures_spec.rb
 - spec/schema_walk_spec.rb
 - spec/spec_helper.rb
 - spec/struct_spec.rb
 - spec/subschema_spec.rb
 - spec/validators_spec.rb
 - spec/whitelist_spec.rb
-homepage: https://github.com/mtkachenk0/paradocs
+homepage: https://paradocs.readthedocs.io/en/latest
 licenses:
 - MIT
 metadata: {}
@@ -149,11 +165,12 @@ test_files:
 - spec/custom_validator.rb
 - spec/dsl_spec.rb
 - spec/expand_spec.rb
+- spec/extensions/payload_builder_spec.rb
+- spec/extensions/structures_spec.rb
 - spec/field_spec.rb
 - spec/helpers.rb
 - spec/policies_spec.rb
 - spec/schema_spec.rb
-- spec/schema_structures_spec.rb
 - spec/schema_walk_spec.rb
 - spec/spec_helper.rb
 - spec/struct_spec.rb