JsonschemaSerializer

This purpose of this gem is to generate JsonSchema. This can be achieved with a builder class or an ActiveRecord wrapper. The gem is available for both Rails 4, 5 or in Ruby standalone projects.

Since the project is still at an early stage, please do not hesitate to open issues / feature requests or fork this repo for pull requests.

Installation

Add this line to your application's Gemfile:

gem 'jsonschema_serializer'

And then execute:

$ bundle

Or install it yourself as:

$ gem install jsonschema_serializer

Usage

You can generate a schema as follows:

schema = JsonschemaSerializer::Builder.build do |b|

  subscriber = b._object title: :subscriber, required: [:age] do |prop|
    prop.merge! b.string :first_name, title: 'First Name'
    prop.merge! b.string :last_name, title: 'Last Name'
    prop.merge! b.integer :age, title: 'Age'
  end

  b.title "a title"
  b.description "a description"
  b.required :a, :b, :c
  b.properties.tap do |p|
    p.merge! b.string :a, description: "abc"
    p.merge! b.array :subscribers, description: "subscribers", items: subscriber
  end
end

schema.to_json

Allowed parameters for data types:

• array : :default, :description, items: {}||[{}], :minItems, :maxItems, :title
• boolean: :default, :description, :title
• integer: :default, :description, enum: [], :minimum, :maximum, :multipleOf, :title
• number : :default, :description, enum: [], :minimum, :maximum, :multipleOf, :title
• string : :default, :description, :format, :minLength, :title

You can alternatively use an experimental builder for ActiveRecord

serializer = JsonschemaSerializer::ActiveRecord

schema = serializer.from_model(MyActiveRecordClass)
schema = serializer.from_model(MyActiveRecordClass, only: %[desired1 desired2])
schema = serializer.from_model(MyActiveRecordClass, except: %[ignored1 ignored2])

# You can manipulate the resulting schema

schema.tap do |s|
  s.title "a title"
  s.description "a description"
end

schema.to_json

Rails

At this stage, a first usage within a Rails application could be a rake task dumping the schemas inside the public folder.

# lib/tasks/jsonschemas.rake
require 'fileutils'

task dump_jsonschemas: :environment do
  Rails.application.eager_load!
  models = ActiveRecord::Base.descendants

  output_path = Rails.root.join('public', 'data')
  # Ensure that the destination path exists
  FileUtils.mkdir_p(output_path)

  models.each do |model|
    # Skip abstract classes
    if model.table_name
      file_path = output_path.join("#{model.model_name.param_key}.json")
      schema = JsonschemaSerializer::ActiveRecord.from_model(model)

      puts "Creating #{file_path} ..."
      File.open(file_path, 'w') { |f| f.write(schema.to_json) }
    else
      puts "Skipping abstract class #{model.to_s} ..."
    end
  end
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

In order to test against serveral ruby and rails versions, you can simply run scripts/run_all_tests. In the gnome-terminal you may need to run /bin/bash --login scripts/run_all_test.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/mberlanda/jsonschema_serializer. Please ensure to keep the test coverage at 100% and follow the angularjs commit message conv.entions.