mtkachenk0 / paradocs

Ruby validation and documentation generation. Write validation code and get generated documentation that you don't have to maintain!

Paradocs: Extended Parametric gem + Documentation Generation

Declaratively define data schemas in your Ruby objects, and use them to whitelist, validate or transform inputs to your programs.

Useful for building self-documeting APIs, search or form objects. Or possibly as an alternative to Rails' strong parameters (it has no dependencies on Rails and can be used stand-alone).

Installation

$ gem install paradocs

Or with Bundler in your Gemfile.

gem 'paradocs'

Getting Started

Define a schema

schema = Paradocs::Schema.new do
  field(:title).type(:string).present
  field(:status).options(["draft", "published"]).default("draft")
  field(:tags).type(:array)
end

Populate and use. Missing keys return defaults, if provided.

form = schema.resolve(title: "A new blog post", tags: ["tech"])

form.output # => {title: "A new blog post", tags: ["tech"], status: "draft"}
form.errors # => {}

Learn more

Please read the documentation

paradocs's Issues

Implement idle policy

Idle policy is a policy that doesn't raise any error and passes validation anyways, but executes a block if the validation logic actually failed.

Any policy should be able to be run as idle_policy

Document new features

#7, #12, #26 features should be documented

Implement field alias Field#as

For API that have logic changes inside but the structures cannot be modified (backward compatibility) would be usefull to implement method as for field

schema do 
  field(:from_id).present.as(:from_identifier)
end 

the result should not contain from_id but contain from_identifier with the very value of from_id

# Input:
{from_id: 1}
# Output:
{from_identifier: 1}

Allow passing descriptions for field

Example:

schema do 
  field(:name).type(:string).description("John")
  field(:age).type(:number).description("This field represents your age")
end

Generate draft schemas from objects

It can be used for faster enrollment. a method which takes an object and outputs somewhere (STDOUT) a Paradocs::Schema declaration syntax that matches the given schema

• save the nesting
• detect type of the field
• all the given fields are present (?)

Try using i18n gem for descriptions managing

Allow passing example for field

It can be used for payload generation.

schema do 
  field(:name).type(:string).example("John")
  field(:age).type(:number).example(23)
  field(:gender).type(:string).options(:m, :f) # example can be random from the options unless defined
  field(:subscribe).type(:boolean).default(:true) # example can be default unless defined
end

Swagger compatability

Extract schema metadata into a swagger compatible format