paradocs 1.1.0 → 1.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0df2185fac7b1e70254c9531622e135c6609f309
-  data.tar.gz: 701ec92673e9044bc8a8384e251276aa7863d37e
+  metadata.gz: ba77710f31f4b6d12c2c764807c1274a7409e18f
+  data.tar.gz: 79e70eed1f40fbc5b2c7fab32b935ecee813b7b8
 SHA512:
-  metadata.gz: aa14905a01be3d1d54589aabc53fbc2f14d3a17352742a9eece1e76b324f146d94f5860ae4f59d738007e809c1fb0eb3ae95579d2a8237798e80a7a6f43ff2b9
-  data.tar.gz: 0c5fedee64178f630d403db573b2d8a4e2e4bc44b88e65df636c88aa1d9857836267d77ed34a1236036ff97bb105e37252f4948d46fcdc600850e682a5db082d
+  metadata.gz: 2365143b9765af228b14ed88105837d34fdba6b3da914e7cf71750e6bea120d6418767b7cd94678480b97ab7735af049129c3c180a6f46d7d590630d09f0d490
+  data.tar.gz: eae4b0b0593f473ac51fc5214bef19c8571490cde4a63b6274a755fc81c1099c226030eaeec56eb15eb91e4263062c57d0c31bf7c50bd01038ef3371c7382031

data/README.md

@@ -37,14 +37,4 @@ form.errors # => {}
 ```
 
 ## Learn more
-- [Getting Started](https://github.com/mtkachenk0/paradocs/wiki/Getting-Started)
-- [Built In Policies](https://github.com/mtkachenk0/paradocs/wiki/Policies#built-in-policies)
-	- [Type Policies](https://github.com/mtkachenk0/paradocs/wiki/Policies#type-coercions)
-	- [Presence Policies](https://github.com/mtkachenk0/paradocs/wiki/Policies#presence-policies)
-  - [Custom Policies](https://github.com/mtkachenk0/paradocs/wiki/Policies#custom-policies)
-- [Schema](https://github.com/mtkachenk0/paradocs/wiki/schema)
-	- [Expanding fields dynamically](https://github.com/mtkachenk0/paradocs/wiki/schema#expanding-fields-dynamically)
-	- [Multiple schema definitions](https://github.com/mtkachenk0/paradocs/wiki/schema#multiple-schema-definitions)
-- [Documentation Generation](https://github.com/mtkachenk0/paradocs/wiki/Documentation-Generation)
-- [What if my fields are conditional?!](https://github.com/mtkachenk0/paradocs/wiki/subschema)
-- [For those who need more: RTFM](https://github.com/mtkachenk0/paradocs/wiki)
+Please read the [documentation](https://paradocs.readthedocs.io/en/latest)

data/docs/changelog.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 1.1.2
+- Regenerate structures each time without saving them into instance attributes.
+
+## 1.1.1
+- Fixed bug with missing `errors` meta key in `Structure#all_nested` and `Structure#all_flatten` methods.
+- Fixed bug with absent `nested_name` meta key in `#Structure#all_nested` method.
+- Added opportunity to sort generated by `PayloadBuilder` payload in the way it is described in schema.
+
+## 1.1.0
+> `Schema#structure` is not comptatible with previous versions
+
+- Added `Paradocs::Extensions::StructureBuilder`. See [more](payload_builder)
+- `Parardocs::Extensions::Structure` has replaced `Paradocs::Extensions::Insides` and changed `Schema#structure` behavior
+- `Paradocs::Extensions::Structure` got more structure generation methods. See [Documentation Generation](documentation_generation)
+

data/docs/documentation_generation.md

@@ -188,12 +188,16 @@ all_nested[:subschema] # =>
     required:  true,
     present:   true,
     json_path: "$.data",
+    nested_name: "data",
     structure: {
-      "role"       => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true},
-      "extra"      => {type: :array, required: true, json_path: "$.data.extra[]", structure: {"extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra"}}},
-      "test_field" => {required: true, present: true, json_path: "$.data.test_field"},
-      "id"         => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id"},
-      "name"       => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true}
+      "role"       => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true, nested_name: "data.role"},
+      "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"}}
+      }
     }
   }
 }
@@ -205,12 +209,16 @@ all_nested[:test_subschema] # =>
     required:  true,
     present:   true,
     json_path: "$.data",
+    nested_name: "data",
     structure: {
-      "role"  => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true},
-      "extra" => {type: :array, required: true, json_path: "$.data.extra[]", structure: {"extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra"}}},
-      "test1" => {required: true, present: true, json_path: "$.data.test1"},
-      "id"    => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id"},
-      "name"  => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true}
+      "role"  => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true, nested_name: "data.role"},
+      "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"}}
+      }
     }
   }
 }
@@ -219,33 +227,38 @@ all_nested[:test_subschema] # =>
 ## Structure#all_flatten
 > This method returns all available combinations of schema (built on subschema) without nesting (the same way as Structure#flatten method does)
 
-Schema is the same as described in Structure#all_nested
+Schema is the same as described in `Structure#all_nested`
 ```rb
 schema.structure.all_flatten # =>
 {
   subschema: {
     _errors: [],
-    "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"}
+    "data"             => {type: :object, required: true, present: true, json_path: "$.data", nested_name: "data"},
+    "data.id"          => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id", nested_name: "data.id"},
+    "data.name"        => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true, nested_name: "data.name"},
+    "data.role"        => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true, nested_name: "data.role"},
+    "data.extra"       => {type: :array, required: true, json_path: "$.data.extra[]", nested_name: "data.extra"},
+    "data.extra.extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra", nested_name: "data.extra.extra"},
+    "data.test_field"  => {required: true, present: true, json_path: "$.data.test_field", nested_name: "data.test_field"}
   },
   test_subschema: {
     _errors: [],
-    "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"}
+    "data"             => {type: :object, required: true, present: true, json_path: "$.data", nested_name: "data"},
+    "data.id"          => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id", nested_name: "data.id"},
+    "data.name"        => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true, nested_name: "data.name"},
+    "data.role"        => {type: :string, options: ["admin", "user"], default: "user", json_path: "$.data.role", mutates_schema: true, nested_name: "data.role"},
+    "data.extra"       => {type: :array, required: true, json_path: "$.data.extra[]", nested_name: "data.extra"},
+    "data.extra.extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra", nested_name: "data.extra.extra"},
+    "data.test1"       => {required: true, present: true, json_path: "$.data.test1", nested_name: "data.test1"}
   }
 }
 ```
 
+## Passing a block
+Given block to the methods above (`#flatten`, `#nested`, `#all_flatten`, `#all_nested`) will be executed for
+each field, passing you as arguments `field.key` and `field.meta`. Mutating the second argument `field.meta`
+will reflect onto returned `meta`.
+
 ## Schema#walk
 
 The `#walk` method can recursively walk a schema definition and extract meta data or field attributes.

data/docs/payload_builder.md

@@ -1,9 +1,8 @@
 # Generate examples from the Schema
 
-> Schema instance provides #example_payloads method that returns example of all possible structures.
+> `Schema` instance provides `#example_payloads` method that returns example of all possible structures.
 
-NOTE: PayloadBuilder sets nil values by default. If options are given - builder will take on of them, if default is set - builder will use it.
-> PayloadBuilder#build! method takes a block as argument that may help you adding your custom rules.
+NOTE: `PayloadBuilder` sets nil values by default. If options are given - builder will take on of them, if default is set - builder will use it.
 
 #### Example schema
 ```ruby
@@ -59,12 +58,14 @@ schema.example_payloads.to_json # =>
 ```
 
 ## Customize payload generation logic
-PayloadBuilder#build! allows passing a block that will receive the following arguments:
+`PayloadBuilder#build!` arguments:
 
-- key: Field name
-- meta: Field meta data (that includes (if provided) field types, presence data, policies and other meta data
-- example_value: Provided by generator example value.
-- skip_word: Return this argument back if you want this item to be ommitted.
+1. `sort_by_schema: true` will try to return payload in the same way as declared in the schema.
+2. `&block` will be executed for each key receiving the following arguments:
+	- `key`: Field name
+	- `meta`: Field meta data (that includes (if provided) field types, presence data, policies and other meta data
+	- `example_value`: Provided by generator example value.
+	- `skip_word`: Return this argument back if you want this item to be ommitted.
 
 ```rb
 block = Proc.new do |key, meta, example, skip_word|

data/lib/paradocs/default_types.rb

@@ -73,16 +73,6 @@ module Paradocs
     end
   end
 
-  Paradocs.policy :split do
-    coerce do |v, k, c|
-      v.kind_of?(Array) ? v : v.to_s.split(/\s*,\s*/)
-    end
-
-    meta_data do
-      {type: :array}
-    end
-  end
-
   Paradocs.policy :datetime do
     coerce do |v, k, c|
       DateTime.parse(v.to_s)

data/lib/paradocs/extensions/payload_builder.rb

@@ -8,8 +8,9 @@ module Paradocs
         @skip_word  = skip_word
       end
 
-      def build!(&block)
-        structure.all_nested.map { |name, struct| [name, build_simple_structure(struct, &block)] }.to_h
+      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
@@ -20,7 +21,8 @@ module Paradocs
           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, ex_value]
+          key = value[:alias] || key
+          [key.to_s, ex_value]
         end.compact.to_h
       end
 

data/lib/paradocs/extensions/structure.rb

@@ -14,12 +14,8 @@ module Paradocs
         @root               = root
       end
 
-      def flush!
-        @nested, @all_nested, @flatten, @all_flatten = [nil] * 4
-      end
-
       def nested(&block)
-        @nested ||= schema.fields.each_with_object({errors => [], subschemes => {}}) do |(_, field), result|
+        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)
@@ -27,8 +23,10 @@ module Paradocs
           else
             result[errors] += field.possible_errors
           end
-          result[field.key] = meta unless ignore_transparent && field.transparent?
-          yield(field.key, meta) if block_given?
+
+          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|
@@ -39,12 +37,13 @@ module Paradocs
       end
 
       def all_nested(&block)
-        @all_nested ||= all_flatten(&block).each_with_object({}) do |(name, struct), obj|
+        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(".")
@@ -60,17 +59,18 @@ module Paradocs
       end
 
       def all_flatten(schema_structure=nil, &block)
-        return @all_flatten if @all_flatten
         schema_structure ||= flatten(&block)
         if schema_structure[subschemes].empty?
           schema_structure.delete(subschemes) # don't include redundant key
-          return @all_flatten = {DEFAULT => schema_structure}
+          return {DEFAULT => schema_structure}
         end
-        @all_flatten = schema_structure[subschemes].each_with_object({}) do |(name, subschema), result|
+        schema_structure[subschemes].each_with_object({}) do |(name, subschema), result|
           if subschema[subschemes].empty?
-             result[name] = schema_structure.merge(subschema)
-             result[name].delete(subschemes)
-             next result[name]
+            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|
@@ -80,7 +80,7 @@ module Paradocs
       end
 
       def flatten(&block)
-        @flatten ||= schema.fields.each_with_object({errors => [], subschemes => {}}) do |(_, field), obj|
+        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?
@@ -105,7 +105,8 @@ module Paradocs
     private
 
       def collect_meta(field, root)
-        json_path = root.empty? ? "$.#{field.key}" : "#{root}.#{field.key}"
+        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)

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

@@ -5,7 +5,7 @@ module Paradocs
     class Format < Paradocs::BasePolicy
       attr_reader :message
 
-      def initialize(fmt, msg = "invalid format")
+      def initialize(fmt, msg="invalid format")
         @message = msg
         @fmt = fmt
       end
@@ -18,12 +18,23 @@ module Paradocs
         !payload.key?(key) || !!(value.to_s =~ @fmt)
       end
     end
+
+    class Split < Paradocs::BasePolicy
+      def initialize(delimiter=/\s*,\s*/)
+        @delimiter = delimiter
+      end
+
+      def coerce(v, *)
+        v.kind_of?(Array) ? v : v.to_s.split(@delimiter)
+      end
+    end
   end
 
   # Default validators
   EMAIL_REGEXP = /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z]+)*\.[a-z]+\z/i.freeze
 
   Paradocs.policy :format, Policies::Format
+  Paradocs.policy :split, Policies::Split
   Paradocs.policy :email, Policies::Format.new(EMAIL_REGEXP, 'invalid email')
 
   Paradocs.policy :noop do

data/lib/paradocs/schema.rb

@@ -181,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
 

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.1.0"
+  VERSION = "1.1.5"
 end

data/mkdocs.yml

@@ -13,4 +13,5 @@ nav:
   - 'payload_builder.md'
   - 'custom_configuration.md'
   - 'faq.md'
+  - 'changelog.md'
 

data/paradocs.gemspec

@@ -8,7 +8,7 @@ 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://paradocs.readthedocs.io/en/latest"
   spec.license       = "MIT"

data/spec/extensions/payload_builder_spec.rb

@@ -22,7 +22,7 @@ describe Paradocs::Extensions::PayloadBuilder do
         end
         subschema(:fooschema) { }
         subschema(:barschema) do
-          field(:barfield).present.type(:boolean)
+          field(:barfield).present.type(:boolean).as(:bar_field)
         end
       end
     end
@@ -32,7 +32,7 @@ describe Paradocs::Extensions::PayloadBuilder 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[: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({
@@ -57,7 +57,7 @@ describe Paradocs::Extensions::PayloadBuilder do
     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[: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({

data/spec/extensions/structures_spec.rb

@@ -18,8 +18,8 @@ describe Paradocs::Extensions::Structure 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(: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
@@ -64,17 +64,20 @@ describe Paradocs::Extensions::Structure do
           test_field: {required: true, present: true, json_path: "$.data.test_field", nested_name: "data.test_field"}
         }
       })
-      expect(data_structure[:id]).to eq({
+      expect(data_structure[:user_id]).to eq({
         type: :integer,
         required: true,
         present: true,
         policy_with_error: {errors: [ArgumentError]},
-        json_path: "$.data.id",
-        nested_name: "data.id"
+        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",
@@ -129,17 +132,20 @@ describe Paradocs::Extensions::Structure do
           json_path: "$.data.extra[].extra",
           policy_with_silent_error: {errors: []}
         },
-        "data.id" => {
+        "data.user_id" => {
           type: :integer,
           required: true,
           present: true,
-          json_path: "$.data.id",
+          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" => {
@@ -174,20 +180,20 @@ describe Paradocs::Extensions::Structure do
     it "generates N structures, where N = number of unique combinations of applied subschemas" do
       expect(schema.structure.all_flatten).to eq({
         subschema: {
-          _errors: [],
+          _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.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: [],
+          _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.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"},
@@ -201,34 +207,41 @@ describe Paradocs::Extensions::Structure 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:     [],
+        _errors:     [ArgumentError],
         "data" => {
-          type:      :object,
-          required:  true,
-          present:   true,
-          json_path: "$.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", mutates_schema: true},
-            "extra"      => {type: :array, required: true, json_path: "$.data.extra[]", structure: {"extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra"}}},
-            "test_field" => {required: true, present: true, json_path: "$.data.test_field"},
-            "id"         => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id"},
-            "name"       => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true}
+            "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:     [],
+        _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", mutates_schema: true},
-            "extra" => {type: :array, required: true, json_path: "$.data.extra[]", structure: {"extra" => {default: false, policy_with_silent_error: {errors: []}, json_path: "$.data.extra[].extra"}}},
-            "test1" => {required: true, present: true, json_path: "$.data.test1"},
-            "id"    => {type: :integer, required: true, present: true, policy_with_error: {errors: [ArgumentError]}, json_path: "$.data.id"},
-            "name"  => {type: :string, label: "very important staff", json_path: "$.data.name", mutates_schema: true}
+            "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"}}}
           }
         }
       })

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

@@ -16,7 +16,7 @@ describe Paradocs::Schema do
 
   subject do
     described_class.new do
-      field(:title).policy(:string).present
+      field(:title).policy(:string).present.as(:article_title)
       field(:price).policy(:integer).meta(label: "A price")
       field(:status).policy(:string).options(['visible', 'hidden'])
       field(:tags).policy(:split).policy(:array)
@@ -33,8 +33,8 @@ describe Paradocs::Schema do
   describe "#structure" do
     it "represents data structure and meta data" do
       sc = subject.structure.nested
-      expect(sc[:title][:present]).to be true
-      expect(sc[:title][:type]).to eq :string
+      expect(sc[:article_title][:present]).to be true
+      expect(sc[:article_title][:type]).to eq :string
       expect(sc[:price][:type]).to eq :integer
       expect(sc[:price][:label]).to eq "A price"
       expect(sc[:variants][:type]).to eq :array
@@ -76,7 +76,7 @@ describe Paradocs::Schema do
 
     output = subject.resolve(payload).output
     expect(output).to eq({
-      title: "title",
+      article_title: "title",
       price: 100,
       status: "visible",
       tags: ["tag"],
@@ -101,7 +101,7 @@ describe Paradocs::Schema do
       variants: [{name: 'v1', sku: 'ABC', stock: '10', available_if_no_stock: true}]
     },
     {
-      title: 'iPhone 6 Plus',
+      article_title: 'iPhone 6 Plus',
       price: 100,
       status: 'visible',
       tags: ['tag1', 'tag2'],
@@ -114,7 +114,7 @@ describe Paradocs::Schema do
       variants: [{name: 'v1', available_if_no_stock: '1'}]
     },
     {
-      title: 'iPhone 6 Plus',
+      article_title: 'iPhone 6 Plus',
       variants: [{name: 'v1', stock: 1, available_if_no_stock: true}]
     })
 

data/spec/struct_spec.rb

@@ -16,13 +16,13 @@ describe Paradocs::Struct do
       include Paradocs::Struct
 
       schema do
-        field(:title).type(:string).present
+        field(:title).type(:string).present.as(:example_title)
         field(:friends).type(:array).default([]).schema friend_class
       end
     end
 
     new_instance = klass.new
-    expect(new_instance.title).to eq ''
+    expect(new_instance.example_title).to eq ''
     expect(new_instance.friends).to eq []
     expect(new_instance.valid?).to be false
     expect(new_instance.errors['$.title']).not_to be_nil
@@ -35,7 +35,7 @@ describe Paradocs::Struct do
       ]
     })
 
-    expect(instance.title).to eq 'foo'
+    expect(instance.example_title).to eq 'foo'
     expect(instance.friends.size).to eq 2
     expect(instance.friends.first.name).to eq 'Ismael'
     expect(instance.friends.first).to be_a friend_class
@@ -154,7 +154,7 @@ describe Paradocs::Struct do
       schema do
         field(:title).type(:string).present
         field(:friends).type(:array).schema do
-          field(:name).type(:string)
+          field(:name).type(:string).as(:person_name)
           field(:age).type(:integer).default(20)
         end
       end
@@ -171,8 +171,8 @@ describe Paradocs::Struct do
     expect(instance.to_h).to eq({
       title: 'foo',
       friends: [
-        {name: 'Jane', age: 20},
-        {name: 'Joe', age: 39},
+        {person_name: 'Jane', age: 20},
+        {person_name: 'Joe', age: 39},
       ]
     })
 
@@ -190,7 +190,7 @@ describe Paradocs::Struct do
       include Paradocs::Struct
 
       schema do
-        field(:title).type(:string).present
+        field(:title).type(:string).present.as(:example_title)
         field(:friends).type(:array).schema do
           field(:name).type(:string)
           field(:age).type(:integer).default(20)
@@ -213,7 +213,7 @@ describe Paradocs::Struct do
       ]
     )
 
-    expect(instance.title).to eq 'foo'
+    expect(instance.example_title).to eq 'foo'
     expect(instance.email).to eq 'email@me.com'
     expect(instance.friends.size).to eq 2
   end

data/spec/subschema_spec.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paradocs
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.5
 platform: ruby
 authors:
 - Maxim Tkachenko
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-09-10 00:00:00.000000000 Z
+date: 2020-11-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -67,8 +67,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0'
-description: Flexible DSL for declaring allowed parameters focused on DRY validation
-  that gives you opportunity to generate API documentation on-the-fly.
+description: Flexible DRY validations with API docs generation done right TLDR; parametrics
+  on steroids.
 email:
 - tkachenko.maxim.w@gmail.com
 - ismaelct@gmail.com
@@ -88,6 +88,7 @@ files:
 - README.md
 - Rakefile
 - bin/console
+- docs/changelog.md
 - docs/custom_configuration.md
 - docs/documentation_generation.md
 - docs/faq.md