paradocs 1.0.24 → 1.1.4

data/lib/paradocs/extensions/payload_builder.rb

@@ -0,0 +1,45 @@
+module Paradocs
+  module Extensions
+    class PayloadBuilder
+      attr_reader :structure, :result
+      attr_accessor :skip_word
+      def initialize(schema, skip_word: :skip)
+        @structure  = schema.structure
+        @skip_word  = skip_word
+      end
+
+      def build!(sort_by_schema: false, &block)
+        result = structure.all_nested.map { |name, struct| [name, build_simple_structure(struct, &block)] }.to_h
+        sort_by_schema ? schema.resolve(result).output : result
+      end
+
+      private
+
+      def build_simple_structure(struct, &block)
+        struct.map do |key, value|
+          key = key.to_s
+          next if key.start_with?(Paradocs.config.meta_prefix) # skip all the meta fields
+          ex_value = restore_one(key, value, &block)
+          next if ex_value == @skip_word
+          key = value[:alias] || key
+          [key.to_s, ex_value]
+        end.compact.to_h
+      end
+
+      def restore_one(key, value, &block)
+        default = value[:default]
+        ex_value = if value[:structure]
+          data = build_simple_structure(value[:structure], &block)
+          value[:type] == :array ? [data] : data
+        elsif default
+          default.is_a?(Proc) ? default.call : default
+        elsif value[:options] && !value[:options].empty?
+          options = value[:options]
+          value[:type] == :array ? options : options.sample
+        end
+        return ex_value unless block_given?
+        yield(key, value, ex_value, @skip_word)
+      end
+    end
+  end
+end

data/lib/paradocs/extensions/structure.rb

@@ -0,0 +1,119 @@
+module Paradocs
+  module Extensions
+    class Structure
+      DEFAULT = :generic
+      %w(errors subschemes).each do |key|
+        define_method(key) { "#{Paradocs.config.meta_prefix}#{key}".to_sym }
+      end
+
+      attr_reader :schema, :ignore_transparent, :root
+      attr_accessor :ignore_transparent
+      def initialize(schema, ignore_transparent=true, root="")
+        @schema             = schema
+        @ignore_transparent = ignore_transparent
+        @root               = root
+      end
+
+      def nested(&block)
+        schema.fields.each_with_object({errors => [], subschemes => {}}) do |(_, field), result|
+          meta, sc = collect_meta(field, root)
+          if sc
+            meta[:structure] = self.class.new(sc, ignore_transparent, meta[:json_path]).nested(&block)
+            result[errors] += meta[:structure].delete(errors)
+          else
+            result[errors] += field.possible_errors
+          end
+
+          field_key = field.meta_data[:alias] || field.key
+          result[field_key] = meta unless ignore_transparent && field.transparent?
+          yield(field_key, meta) if block_given?
+
+          next unless field.mutates_schema?
+          schema.subschemes.each do |name, subschema|
+            result[subschemes][name] = self.class.new(subschema, ignore_transparent, root).nested(&block)
+            result[errors] += result[subschemes][name][errors]
+          end
+        end
+      end
+
+      def all_nested(&block)
+        all_flatten(&block).each_with_object({}) do |(name, struct), obj|
+          obj[name] = {}
+          # sort the flatten struct to have iterated 1lvl keys before 2lvl and so on...
+          struct.sort_by { |k, v| k.to_s.count(".") }.each do |key, value|
+            target = obj[name]
+            key, value = key.to_s, value.clone # clone the values, because we do mutation below
+            value.merge!(nested_name: key) if value.respond_to?(:merge) # it can be array (_errors)
+            next target[key.to_sym] = value if key.start_with?(Paradocs.config.meta_prefix) # copy meta fields
+
+            parts = key.split(".")
+            next target[key] ||= value if parts.size == 1 # copy 1lvl key
+            parts.each.with_index do |subkey, index|
+              target[subkey] ||= value
+              next if parts.size == index + 1
+              target[subkey][:structure] ||= {}
+              target = target[subkey][:structure] # target goes deeper for each part
+            end
+          end
+        end
+      end
+
+      def all_flatten(schema_structure=nil, &block)
+        schema_structure ||= flatten(&block)
+        if schema_structure[subschemes].empty?
+          schema_structure.delete(subschemes) # don't include redundant key
+          return {DEFAULT => schema_structure}
+        end
+        schema_structure[subschemes].each_with_object({}) do |(name, subschema), result|
+          if subschema[subschemes].empty?
+            result[name] = schema_structure.merge(subschema)
+            result[name][errors] += schema_structure[errors]
+            result[name][errors].uniq!
+            result[name].delete(subschemes)
+            next result[name]
+          end
+
+          all_flatten(subschema).each do |sub_name, schema|
+            result["#{name}_#{sub_name}".to_sym] = schema_structure.merge(schema)
+          end
+        end
+      end
+
+      def flatten(&block)
+        schema.fields.each_with_object({errors => [], subschemes => {}}) do |(_, field), obj|
+          meta, sc = collect_meta(field, root)
+          humanized_name = meta.delete(:nested_name)
+          obj[humanized_name] = meta unless ignore_transparent && field.transparent?
+
+          if sc
+            deep_result = self.class.new(sc, ignore_transparent, meta[:json_path]).flatten(&block)
+            obj[errors] += deep_result.delete(errors)
+            obj[subschemes].merge!(deep_result.delete(subschemes))
+            obj.merge!(deep_result)
+          else
+            obj[errors] += field.possible_errors
+          end
+          yield(humanized_name, meta) if block_given?
+          next unless field.mutates_schema?
+          schema.subschemes.each do |name, subschema|
+            obj[subschemes][name] ||= self.class.new(subschema, ignore_transparent, root).flatten(&block)
+            obj[errors] += obj[subschemes][name][errors]
+          end
+        end
+      end
+
+    private
+
+      def collect_meta(field, root)
+        field_key = field.meta_data[:alias] || field.key
+        json_path = root.empty? ? "$.#{field_key}" : "#{root}.#{field_key}"
+        meta = field.meta_data.merge(json_path: json_path)
+        sc = meta.delete(:schema)
+        meta[:mutates_schema] = true if meta.delete(:mutates_schema)
+        json_path << "[]" if meta[:type] == :array
+        meta[:nested_name] = json_path.gsub("[]", "")[2..-1]
+        [meta, sc]
+      end
+    end
+  end
+end

data/lib/paradocs/field_dsl.rb

@@ -32,5 +32,17 @@ module Paradocs
     def length(opts)
       policy :length, opts
     end
+
+    def description(text)
+      meta description: text
+    end
+
+    def as(identifier)
+      meta alias: identifier
+    end
+
+    def example(value)
+      meta example: value
+    end
   end
 end

data/lib/paradocs/schema.rb

@@ -1,14 +1,13 @@
 require "paradocs/context"
 require "paradocs/results"
 require "paradocs/field"
-require "paradocs/extensions/insides"
+require "paradocs/extensions/structure"
+require "paradocs/extensions/payload_builder"
 
 module Paradocs
   class Schema
-    include Extensions::Insides
-
     attr_accessor :environment
-    attr_reader :subschemes
+    attr_reader :subschemes, :structure_builder
     def initialize(options={}, &block)
       @options = options
       @fields = {}
@@ -18,6 +17,7 @@ module Paradocs
       @default_field_policies = []
       @ignored_field_keys = []
       @expansions = {}
+      @structure_builder = Paradocs::Extensions::Structure.new(self)
     end
 
     def schema
@@ -29,6 +29,27 @@ module Paradocs
       f.mutates_schema!(&block)
     end
 
+    def structure(ignore_transparent: true)
+      flush!
+      structure_builder.ignore_transparent = ignore_transparent
+      structure_builder
+    end
+
+    def example_payloads(&block)
+      @example_payloads ||= Paradocs::Extensions::PayloadBuilder.new(self).build!(&block)
+    end
+
+    def walk(meta_key = nil, &visitor)
+      r = visit(meta_key, &visitor)
+      Results.new(r, {}, {})
+    end
+
+    def visit(meta_key = nil, &visitor)
+      fields.each_with_object({}) do |(_, field), m|
+        m[field.key] = field.visit(meta_key, &visitor)
+      end
+    end
+
     def subschema(*args, &block)
       options = args.last.is_a?(Hash) ? args.last : {}
       name = args.first.is_a?(Symbol) ? args.shift : Paradocs.config.default_schema_name
@@ -143,6 +164,11 @@ module Paradocs
       end
     end
 
+    def flush!
+      @fields = {}
+      @applied = false
+    end
+
     protected
 
     attr_reader :definitions, :options
@@ -155,7 +181,8 @@ module Paradocs
       invoke_subschemes!(val, context, flds: flds)
       flds.each_with_object({}) do |(_, field), m|
         r = field.resolve(val, context.sub(field.key))
-        m[field.key] = r.value if r.eligible?
+        key = field.meta_data[:alias] || field.key
+        m[key] = r.value if r.eligible?
       end
     end
 
@@ -205,10 +232,5 @@ module Paradocs
       end
       @applied = true
     end
-
-    def flush!
-      @fields = {}
-      @applied = false
-    end
   end
 end

data/lib/paradocs/struct.rb

@@ -57,6 +57,7 @@ module Paradocs
       # this hook is called after schema definition in DSL module
       def paradocs_after_define_schema(schema)
         schema.fields.keys.each do |key|
+          key = schema.fields[key].meta_data[:alias] || key
           define_method key do
             _graph[key]
           end

data/lib/paradocs/version.rb

@@ -1,3 +1,3 @@
 module Paradocs
-  VERSION = "1.0.24"
+  VERSION = "1.1.4"
 end

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

@@ -8,9 +8,9 @@ Gem::Specification.new do |spec|
   spec.version       = Paradocs::VERSION
   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.description   = %q{Flexible DRY validations with API docs generation done right TLDR; parametrics on steroids.}
   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).as(:bar_field)
+        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", "bar_field" => 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, "bar_field" => 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,250 @@
+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).as(:user_id)
+        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[:user_id]).to eq({
+        type: :integer,
+        required: true,
+        present: true,
+        policy_with_error: {errors: [ArgumentError]},
+        alias: :user_id,
+        json_path: "$.data.user_id",
+        nested_name: "data.user_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.user_id" => {
+          type: :integer,
+          required: true,
+          present: true,
+          alias: :user_id,
+          json_path: "$.data.user_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.user_id"     => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, alias: :user_id, json_path: "$.data.user_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.user_id"     => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, alias: :user_id, json_path: "$.data.user_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"},
+            "user_id"    => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, alias: :user_id, json_path: "$.data.user_id", nested_name: "data.user_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"},
+            "user_id" => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, alias: :user_id, json_path: "$.data.user_id", nested_name: "data.user_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